Javadoc是什么及其使用方法

Javadoc是什么及其使用方法

一、什么是Javadoc
Javadoc从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。
javadoc命令是用来生成自己API文档的，使用方式：使用命令行在目标文件所在目录输入javadoc +文件名.java。
Javadoc用于描述类或者方法的作用。Javadoc可以写在类上面和方法上面。

二、Javadoc的使用方法
1.Javadoc的注解

注解	描述
@author	作者标识
@version	版本号
@return	对函数返回值的描述
@deprecated	标识过期API（为了保证兼容性，仍可用，但不推荐用）
@throws	构造函数或方法会抛出的异常
@see	引用，查看相关的内容，如类，方法，变量等，必须顶头写
{@link 包.类#成员}	引用，同@see，但可写在任意位置
{@value}	对常量注释，如果其值包含在文档中，通过改标签引用常量的值
{@code}}	{@code text}将文本标记为code，会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名，都需要使用@code进行标记

2.描述中使用到的HTML标签
p 换行
pre 保留文本格式，即保留空格和换行符
a 超链接
ul 列表
i 斜体
blockquote 标记引用

三、JavaDoc注解(由JDK定义) - 类
写在类上的文档标注一般分为三段：
第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束。
第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束。
第三段：文档标注，用于标注作者、创建时间、参阅类等信息。
@link： 快速链接到指定代码（ctrl + 点击快速跳转）
@code： {@code text} 将文本标记为code，code内部不会进行html解析，一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。
@author： 用于描述作者
@version： 标注当前版本
@since： 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间。
@see 参阅
@param： 一般类中支持泛型时会通过@param来解释泛型的类型
@deprecated：标识过期API（为了保证兼容性，仍可用，但不推荐用）

四、JavaDoc注解(由JDK定义) - 方法
@param ：后面跟参数名，再跟参数描述
@return：后接返回值的描述
@exception：用于描述方法签名throws对应的异常
@throws 用于描述方法可能抛出的异常
@see：用法与用在类上相同
@value：用于标注在常量上，{@value} 用于表示常量的值。
@inheritDoc：用于注解在重写方法或者子类上，用于继承父类中的Javadoc
1.基类的文档注释被继承到了子类
2.子类可以再加入自己的注释（特殊化扩展）
3.@return @param @throws 也会被继承