JavaDoc注释详解

- 日理万妓 2022-05-28 10:23 223阅读 0赞

javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。

## javadoc标记 ##

javadoc标记包括。

<table> 
 <thead> 
  <tr> 
   <th align="center">标记</th> 
   <th align="center">说明</th> 
   <th align="center">标记类型</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">@author</td> 
   <td align="center">作者标记</td> 
   <td align="center">包、 类、接口</td> 
  </tr> 
  <tr> 
   <td align="center">@version</td> 
   <td align="center">版本号</td> 
   <td align="center">包、 类、接口</td> 
  </tr> 
  <tr> 
   <td align="center">@param</td> 
   <td align="center">方法的入参名及描述信息，如入参有特别要求，可在此注释。</td> 
   <td align="center">构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">@return</td> 
   <td align="center">函数返回值描述</td> 
   <td align="center">方法</td> 
  </tr> 
  <tr> 
   <td align="center">@deprecated</td> 
   <td align="center">标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。</td> 
   <td align="center">包、类、接口、值域、构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">@throws</td> 
   <td align="center">构造函数或方法所会抛出的异常。</td> 
   <td align="center">构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">@exception</td> 
   <td align="center">构造函数或方法所会抛出的异常。</td> 
   <td align="center">构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">@see</td> 
   <td align="center">查看相关内容，如类、方法、变量等。</td> 
   <td align="center">包、类、接口、值域、构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">@since</td> 
   <td align="center">API在什么程序的什么版本后开发支持。</td> 
   <td align="center">包、类、接口、值域、构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@link包.类#成员 标签}</td> 
   <td align="center">链接到某个特定的成员对应的文档中。</td> 
   <td align="center">包、类、接口、值域、构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@value}</td> 
   <td align="center">当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。</td> 
   <td align="center">静态值域</td> 
  </tr> 
  <tr> 
   <td align="center">@see</td> 
   <td align="center">查看相关内容，如类、方法、变量等。</td> 
   <td align="center">包、类、接口、值域、构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">@serial</td> 
   <td align="center">序列化标记</td> 
   <td align="center">用于序列化特殊方法</td> 
  </tr> 
  <tr> 
   <td align="center">@serialField</td> 
   <td align="center">序列化标记</td> 
   <td align="center">用于序列化ObjectStreamField组件</td> 
  </tr> 
  <tr> 
   <td align="center">@serialData</td> 
   <td align="center">序列化标记</td> 
   <td align="center">用于序列化特殊方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@link}</td> 
   <td align="center">创建内部链接</td> 
   <td align="center">包、类、接口、值域、构造函数、方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@linkplain}</td> 
   <td align="center">功能与@link相同，内容显示格式不同</td> 
   <td align="center">包、类、接口、值域、构造函数、方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@docRoot}</td> 
   <td align="center">生成html文档根目录</td> 
   <td align="center">包、类、接口、值域、构造函数、方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@inheritDoc}</td> 
   <td align="center">继承父类的注释文档</td> 
   <td align="center">包、类、接口、值域、构造函数、方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@literal}</td> 
   <td align="center">用于解析特定字符（&lt;,&gt;）</td> 
   <td align="center">包、类、接口、值域、构造函数、 方法</td> 
  </tr> 
  <tr> 
   <td align="center">{@code}</td> 
   <td align="center">使内容在html文件中展示code风格</td> 
   <td align="center">包、类、接口、值域、构造函数、 方法</td> 
  </tr> 
 </tbody> 
</table>

## 标记使用 ##

标记使用请查阅[这里][Link 1]  
在描述性文档字段中，可兼容插入HTML标签以使生成的HTML文件更加易读。比如p,a,br等。

## 命令格式 ##

Javadoc命令格式如下：

***javadoc \[选项\] \[软件包名称\] \[源文件\]***

其中选项有：

*  \-overview <文件> 读取 HTML 文件的概述文档
 *  \-public 仅显示公共类和成员
 *  \-protected 显示受保护/公共类和成员（默认）
 *  \-package 显示软件包/受保护/公共类和成员
 *  \-private 显示所有类和成员
 *  \-help 显示命令行选项并退出
 *  \-doclet <类> 通过替代 doclet 生成输出
 *  \-docletpath <路径> 指定查找 doclet 类文件的位置
 *  \-sourcepath <路径列表> 指定查找源文件的位置
 *  \-classpath <路径列表> 指定查找用户类文件的位置
 *  \-exclude <软件包列表> 指定要排除的软件包的列表
 *  \-subpackages <子软件包列表> 指定要递归装入的子软件包
 *  \-breakiterator 使用 BreakIterator 计算第 1 句
 *  \-bootclasspath <路径列表> 覆盖引导类加载器所装入的类文件的位置
 *  \-source <版本> 提供与指定版本的源兼容性
 *  \-extdirs <目录列表> 覆盖安装的扩展目录的位置
 *  \-verbose 输出有关 Javadoc 正在执行的操作的消息
 *  \-locale <名称> 要使用的语言环境，例如 en\_US 或 en\_US\_WIN
 *  \-encoding <名称> 源文件编码名称
 *  \-quiet 不显示状态消息
 *  \-J<标志> 直接将 <标志> 传递给运行时系统

[Link 1]: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html