1、什么是java文档注释
java语言除了提供基本的代码注释以外，还提供了一种功能更加强大的注释形式：文档注释。如果编写java源代码时添加了合适的文档注释，然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。
2、文档注释的作用
当开发一个大型软件时，需要定义成千上万个类，而且需要很多人参与开发。每个人都会开发一些类，并在类里定义一些方法和域提供给其他人使用，但其他人怎么知道如何使用这些类和方法呢？这时就需要提供一份说明文档，用于说明每个类、每个方法的用途。当其他人使用一个类或者一个方法时，他无需关心这个类或这个方法的具体实现，他只要知道这个类或这个方法的功能即可，然后使用这个类或方法来实现具体的目的，也就是通过调用应用程序接口（API）来编程。API文档就是用来说明这些应用程序接口的文档。对于java语言而言，API文档通常详细的说明了每个类、每个方法的功能及用法。
3、官方API说明文档效果展示
4、生成自己的API文档
4.1 使用javadoc命令生成文档
我在本地磁盘H:\javaDoc下分别建立javaCode1.java、javaCode2.java，并写入相应的内容。
package skylake;
public class javaCode1{
String Sentence;
public static void main(String[] args){
javaCode1 jd1 = new javaCode1("I Love the world!");
}
/** * * @param 参数str是一句你想要大声告诉世界的话. */
javaCode1(String str){
System.out.println("这是一句话 :"+str);
Sentence = str;
}
/** * * @return 返回一串字符串 */
public String getSentence(){
return Sentence;
}
}package skylake;
public class javaCode2{
String Sentence;
int age;
public static void main(String[] args){
javaCode1 jd1 = new javaCode1("I Love the world!");
}
/** * * @param 参数str是一句想要大声告诉世界的话. */
javaCode2(String str){
System.out.println("这是一句话 :"+str);
Sentence = str;
}
/** * * @return 返回一串字符串 */
public String getSentence(){
return Sentence;
}
}在控制台中输入一下命令：
javadoc -d apidoc *.java效果演示
参数介绍
javadoc命令支持通配符，例如使用*.java来代表当前路径下的所有java源文件，javadoc常用的选项有如下几个：
-d : 该选项指定一个路径，用于将生成的API文档放到指定的目录下
-windowtitle : 该选项指定一个字符串，用于设置API文档的浏览器窗口标题
-doctitle: 该选项指定一个HTML格式的文本，用于指定概述页面的标题（只有对处于多个包下的源文件来生成API文档时，才有概述页面）
-header: 该选项指定一个HTML格式的文本，包含每个页面的页眉。
常用的javadoc标记
如果我们希望javadoc工具生成更详细的文档信息，例如方法参数、方法返回值等生成详细的说明信息，则可以利用javadoc标记。常用的javadoc标记如下：
@author：指定java程序的作者
@version：指定源文件的版本
@deprecated：不推荐使用的方法
@param：方法参数说明信息
@return：方法返回值说明信息
@see：“参见”，用于指定交叉参考的内容
@exception：抛出异常的类型
@throws ：抛出的异常，和exception同义
4.2 在Eclipse中生成API文档
在eclipse中选择Project–>Generate Javadoc–>选择你想要生成doc的项目工程和文档保存的路径，设置结束后，点击Finish（也可以在next中继续设置一些选项，如文档的标题等）
效果演示
5、总结
这两种方法都可以很快速的帮助我们生成API文档，不过使用命令的时候，经常会遇到编码方面的错误。
eclipse已经帮助我们完成了大量的工作，可以很方便的促进我们的开发。关于API文档这一块儿，如果想要写出高质量的文档，还是应该去参考官方的API文档格式。