java的三种注释方式与java文档注释的使用方法

• 一、java 注释的三种方法
• 二、单行注释与多行注释
• 三、文档注释与如何使用文档注释并生成 API 文档
  

  ---

一、java 注释的三种方法

在 java 注释中一共有三种类型：

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

  ---

二、单行注释与多行注释

• 单行注释：单行注释只需要使用双斜线即可（//）。
• 多行注释：多行注释是指一次性将程序多的多行代码注释掉，使用斜线加与星号开始，星号与斜线结束。即/* */
  

  ---

三、文档注释与如何使用文档注释并生成 API 文档

• 如何使用文档注释：
  文档注释一斜线后跟两个星号开始，与星号后跟一个斜线结束。即/** */。中间部分全部都是文档注释，会被提取到 API 文档中。
  同时 Java 9 的 API 文档已经支持 HTML 5 规范，因此为了得到完全兼容 HTML 5 的 API 文档，必须保证文档中的内容完全兼容 HTML 5 规范。
• 如何生成 API 文档：
  Java 提供 javadoc 工具帮助将文档注释转换成为 API 文档，同时 javadoc 默认只会处理 public 或 protected 修饰的内容，如果开发者确实希望 javadoc 工具可以提取 private 修饰的内容，则可以在使用 javadoc 工具时增加-private 选项。
  javadoc 命令的基本用法如下：

javadoc 选项 Java 源文件|包

javadoc 命令对源文件、包生成 API 文档，在上面的语法中，Java 源文件可以支持通配符。例如，使用*.java 来代表当前路径下所有的 Java 源文件。
javadoc 的常用选项有如下几个：

-d<directory> ：指定生成文档到哪个目录
-windowtitle<text> ：该选项制定一个字符串，用于设置 API 文档的浏览器窗口标题。
-doctitle<html-code> ：该选项指定一个 HTML 格式的文本，用于指定概述页面的标题，只有对处于多个包下的源文件来生成 API 文档时，才有概述页面。
-header<html-code> ：该选项制定一个 HTML 格式的文本，包含每个页面的页眉。

除此之外，如果希望 javadoc 生成更加详细的文档信息，则可以使用 javadoc 标记。常用的 javadoc 标记如下：

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

javadoc 工具默认不会提取@author和@version两个标记的信息，如果需要提取这两个标记的信息，应该在使用 javadoc 工具时指定-author和-version两个选项。

参考资料：

• 疯狂 Java 讲义（第四版） 李刚 编著
  

  ---

本文章笔记版本地址：http://ccdd6ec5.wiz03.com/share/s/3cTmX51TMQ-b2QTact03UPg813r34-12F4Sz2GJw2q1qMFQ3