JavaDoc使用和文档生成

介绍

所有的Javadoc注释以/*开始，以/结束，每个注释包含一些描述性的文本及若干个Javadoc标签。描述性的文本不但可以用平面文本，还可以使用HTML文本；Javadoc标签一般以"@“为前缀，有的也以”{@“为前缀，以”}"结束，如{@value }。

JavaDoc标签

标签	描述	示例
@author	标识一个类的作者	@author description
@deprecated	指名一个过期的类或成员	@deprecated description
{@docRoot}	指明当前文档根目录的路径	Directory Path
@exception	标志一个类抛出的异常	@exception exception-name explanation
{@inheritDoc}	从直接父类继承的注释	Inherits a comment from the immediate surperclass.
{@link}	插入一个到另一个主题的链接	{@link name text}
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体	Inserts an in-line link to another topic.
@param	说明一个方法的参数	@param parameter-name explanation
@return	说明返回值类型	@return explanation
@see	指定一个到另一个主题的链接	@see anchor
@serial	说明一个序列化属性	@serial description
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据	@serialData description
@serialField	说明一个ObjectStreamField组件	@serialField name type description
@since	标记当引入一个特定的变化时	@since release
@throws	和 @exception标签一样.	The @throws tag has the same meaning as the @exception tag.
{@value}	显示常量的值，该常量必须是static属性。	Displays the value of a constant, which must be a static field.
@version	指定类的版本	@version info

标记位置限制：

标记	范围
@see、@deprecated、@author、@version	类或者接口文档注释
@see、@deprecated、@param、@return、@throws、@exception	方法或者构造器文档注释
@see、@deprecated	文档注释

标签详细介绍

概要描述

@see

可以通过这个标签在当前点链接到某个类、值域或方法的说明上。为了链接到当前类的值域或方法上，在值域和方法名前必须带一个#号，如：
@see #getSex() 链接方法
@see #MALE 链接值域
@see javadoc.tool.Car 链接类
@see javadoc.tool.Car#drive(int,int)：链接到drive(int direction,int speed)
@see javadoc.tool.Car#drive(int)：链接到drive(int speed)

@link

@link：{@link 包名.类名#方法名(参数类型)} 用于快速链接到相关代码
@link的@see很相似，唯一不同的是它可以嵌套在注释的描述文本中，在生成Javadoc文档时转换成一个关联链接。如：

@param sex int 性别，有效值是{@link #MALE }和{@link #FEMALE}
@see javadoc.tool.Car#drive(int)

@code

@code： {@code text} 将文本标记为code
一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。
将文本标记为代码样式的文本，在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式

@param

一般类中支持泛型时会通过@param来解释泛型的类型
@param <E> the type of elements in this list

@author

详细描述后面一般使用@author来标记作者，如果一个文件有多个作者来维护就标记多个@author，@author 后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址)
@author Rod Johnson
@author Igor Hersht, [email protected]
@author <a href=“mailto:[email protected]” >Ovidiu Predescu</a>

@since

@since 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间,从以下版本开始
@since JDK1.8

@return

@return 跟返回值的描述
@return {@code true} if the {@code String} is not {@code null}, its

@throws

@throws 跟异常类型 异常描述 , 用于描述方法内部可能抛出的异常
@throws IllegalArgumentException when the given source contains invalid encoded sequences

@exception

用于描述方法签名throws对应的异常
@exception IllegalArgumentException if key is null.

@value

用于标注在常量上，{@value} 用于表示常量的值
默认数量 {@value}
private static final Integer QUANTITY = 1;

@inheritDoc

@inheritDoc用于注解在重写方法或者子类上，用于继承父类中的Javadoc

基类的文档注释被继承到了子类
子类可以再加入自己的注释（特殊化扩展）
@return @param @throws 也会被继承

生成javaDoc方式

指定编码选项 -encoding utf-8

使用CMD生成注释文档

可以利用Javadoc工具将Java源代码中的文档注释自动转化成API文档。

• -d(directory):该选项指定一个路径，用于将生成的API文档放到指定目录下。
• -windowtitle(text):该选项指定一个字符串，用于设置API文档的浏览器窗口标题。
• -doctitle(html-code):该选项指定一个HTML格式的文本，用于指定概述页面的标题。
  注意：只有对处于多个包下的源文件来生成API文档时，才有概述页面。
• -header(html-code):该选项指定一个HTML格式的文本，包含每个页面的页眉。
• 除此之外，javadoc命令还包含了大量其他选项，我们可以通过在命令行窗口执行javadoc -help命令来查看javadoc命令的所有选项。`

javadoc -encoding utf-8 Fish.java javaDoc文档生成在cmd当前文件夹下，一般指定路径

命令：

D:\work\Java\jdk1.8.0_144\bin\javadoc.exe -encoding utf-8 -d E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\ E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java

• D:\work\Java\jdk1.8.0_144\bin\javadoc.exe //表示javadoc.exe 位置
• -encoding utf-8 //参数 设置字符utf-8
• -d E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\ //生成注释文档保存的文件
• E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java //要查询的源码入口

C:\Users\bellus>D:\work\Java\jdk1.8.0_144\bin\javadoc.exe -encoding utf-8 -d E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\  E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java
正在加载源文件E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java...
正在构造 Javadoc 信息...
E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java:3: 错误: 程序包org.springframework.boot不存在
import org.springframework.boot.SpringApplication;
                               ^
E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java:4: 错误: 程序包org.springframework.boot.autoconfigure不存在
import org.springframework.boot.autoconfigure.SpringBootApplication;
                                             ^
E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java:6: 错误: 找不到符号
@SpringBootApplication
 ^
  符号: 类 SpringBootApplication
正在创建目标目录: "E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\"
标准 Doclet 版本 1.8.0_144
正在构建所有程序包和类的树...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\Application.html...
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\package-frame.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\package-summary.html...
javadoc: 警告 - 找不到类SpringBootApplication。
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\package-tree.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\constant-values.html...
正在构建所有程序包和类的索引...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\overview-tree.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\index-all.html...
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
javadoc: 警告 - 找不到类SpringBootApplication。
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\deprecated-list.html...
javadoc: 警告 - 找不到类SpringBootApplication。
正在构建所有类的索引...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\allclasses-frame.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\allclasses-noframe.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\index.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\help-doc.html...
16 个警告

C:\Users\bellus>

使用eclipse生成注释文档

eclipse -> 选中项目右键 -> Export -> java -> javadoc -> Next

配置javadoc.exe执行文件目录，要生成的项目，文档生成目录

可忽略或者默认

设置编码和jdk版本

完成。