文章目录
什么是文档注释
和大部分语言一样,Java支持单行注释//和多行注释/**/的形式.除此之外Java 9以后的版本新增了文档注释,这是一种用于生成API文档的注释,所谓API,即Application Programming Interface,应用编程接口,它就像是一个说明书,用来说明一个用户自定义的类的接口信息、方法用途和使用方式.这样当其他人使用你编写的类时,就无需关心其内部实现,只需知道其接口组成和用途即可使用.Java语言有很多系统类,这些类自然也有其API文档,用来告诉开发人员如何使用这些类,Java API可以在这里看到.
文档注释的写法规范和API的生成
文档注释以/**开始,以*/结束,其中间每一行都以*开头,开始和结束标志中间的内容就是文档注释,文档注释完全兼容HTML5规范,因此为了得到完全兼容的API文档,请确保文档注释的内容完全符合HTML5规范.
此外,还可以为成员变量信息、方法参数和返回值等生成更详细的信息,可以添加一些说明,以@开头,如:
@author: 指定源文件的作者@version: 指定源文件的版本信息@deprecated: 已过时的/不建议使用的内容@param: 方法的参数说明信息@return: 方法的返回值信息@see: “参见”,用于指定交叉参考的内容@exception: 抛出异常的类型@throws: 抛出的异常,同义于@exception@since： 内容自什么版本之后有效{@link}： - 链接到某个特定的内容对应的文档中@value： 当对常量进行注释时,通过该标签来引用常量的值- 还有一些不常用的不再列出,请自行查阅
这些修饰信息能够在代码中出现的位置也是有限定的,具体可参照下表:
| 位置 | 可使用的修饰符 |
|---|---|
| 包/类/接口文档注释 | @author、@version、@deprecated、@see、{@link}、@since |
| 方法/构造器文档注释 | @see、@deprecated、@param、@return、@throws、@exception、{@link}、@since |
| 成员变量文档注释 | @see、@deprecated、@since、{@link} |
| 静态成员 | @{value} |
使用javadoc命令来提取你的API文档,用法请自行查看帮助.
需说明一点:javadoc默认不会提取private的成员变量,@author和@version等信息,需要加上对应参数,如:
-private、-author、-version,如以下程序:
/**
* 描述:<br>
* 测试Javadoc的一个小程序
* 我的博客:<a href="https://blog.csdn.net/AAMahone">AAMahone的博客</a><br>
* Program Name: DocTest<br>
* @author Aaron Alex Mahone
* @version 0.01
*/
class HelloWorld {
/**
* 字符串常量,值为{@value}
*/
final String name = "HelloWorld";
/**
* 这是一个HelloWorld的无参构造器
* @return 构造函数返回name
*/
public String HelloWorld() {
System.out.println(name);
return name;
}
/**
* @param a 被除数
* @param b 除数
* @throws Exception 注意除零异常
* @return 返回a/b的结果
*/
public int devide(int a,int b) throws Exception {
try {
return a/b;
} catch(Exception e) {
System.out.println(e.getMessage());
}
}
}
public class DocTest {
/**
* @deprecated 不要使用useless,它没有用
*/
private double useless;
/**
* 主函数,程序入口
* @param args 主函数参数
*/
public static void main(String[] args) {
HelloWorld hello;
System.out.println(hello.devide(1/2));
}
}
使用javadoc工具提取API:
javadoc -d ./API -version -author -private DocTest.java
之后会在当前目录的API子目录下生成一系列文件(html文件和其它相关文件),打开html文件即可查看API