Java 的三种注释

一、Java 注释的三种方法

• 单行注释
• 多行注释
• 文档注释

二、单行注释与多行注释

• 单行注释使用双斜线，即 //。
• 多行注释从斜线加星号开始，到星号加斜线结束，即 /* */。

三、文档注释与生成 API 文档

文档注释从斜线后跟两个星号开始，到星号后跟一个斜线结束，即 /** */。中间部分会被提取到 API 文档中。Java 9 的 API 文档已经支持 HTML 5，因此文档中的内容需要兼容 HTML 5。

Java 提供 javadoc 工具把文档注释转换成 API 文档。javadoc 默认只处理 public 或 protected 修饰的内容。如果需要提取 private 修饰的内容，使用 javadoc 时增加 -private 选项。

javadoc 选项 Java源文件|包

Java 源文件可以支持通配符，例如用 *.java 代表当前路径下所有 Java 源文件。常用选项:

-d <directory>        指定生成文档的目录
-windowtitle <text>   设置浏览器窗口标题
-doctitle <html-code> 指定概述页面的标题
-header <html-code>   指定每个页面的页眉

常用的 javadoc 标记:

@author      指定程序的作者
@version     指定源文件的版本
@deprecated  不推荐使用的方法
@param       方法的参数说明
@return      方法的返回说明
@see         指定交叉参考的内容
@exception   抛出异常的类型
@throws      抛出的异常，和 @exception 同义

javadoc 默认不会提取 @author 和 @version。需要这两个标记时，使用 -author 和 -version 选项。

参考资料: 疯狂 Java 讲义（第四版），李刚编著。