最近看源码,一些Javadoc常见的注释整理下
Javadoc是Sun公司提供的一个技术,从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。
Javadoc命令是用来生成自己的API文档,使用方式:
javadoc 源文件名.java
javadoc -d 文档存放目录 源文件名.java
通过IDEA生成Javadoc : Tools -> Generate JavaDoc
javadoc标签
标签 | 说明 |
---|---|
@author | 作者标识 |
@version | 版本号 |
@return | 对函数返回值的描述 |
@deprecated | 标识过期API(为了保证兼容性,仍可用,但不推荐用) |
@throws | 构造函数或方法会抛出的异常 |
@exception | 同@throws |
@see | 引用,查看相关的内容,如类,方法,变量等,必须顶头写 |
{@link 包.类#成员} | 引用,同@see,但可写在任意位置 |
{@value} | 对常量注释,如果其值包含在文档中,通过改标签引用常量的值 |
{@code}} | {@code text}将文本标记为code,会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名,都需要使用@code进行标记 |
@param | 说明方法的参数 |
@inheritDoc | 用于继承父类中的Javadoc,父类的文档注释,被继承到了子类 |
javadoc注释规范
一、 Java文档
// 注释一行
/ * */ 注释若干行
/** ……*/ 注释若干行,写入Javadoc文档
二、文档格式
写在类上的文档标注一般分为三段:
- 第一段:概要描述,通常用一句话或者一段话简要描述该类的作用,以英文句号结束
- 第二段:详细描述,通常用一段或者多段话来详细描述该类的作用,一般每段话都以英文句号作为结束
- 第三段:文档标注,用于标注作者,创建时间,参阅类等信息
生成文档是HTML格式。
换行<br>
分段<p>(写在段前))
示例
/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示,false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}