javadoc语法

那么今天就给大家详细讲讲Java支持的三种注释方式：单行注释、多行注释和文档注释。

“//”：以双斜杠开头，通常习惯在后面加上一个空格，这样表示单行注释，顾名思义，这样的注释方法，其注释的内容只能在一行中。所以通常用于解释一行代码语句。

public class annotation {    public static void main(String[] args) {        // 控制台输入“java单行注释”字符串        System.out.println("java单行注释");    }}

以“/”开头，以“/”结束，中间是注释内容，允许注释多行的内容。为了高可读性和美观，一般首行和尾行不写注释信息。

public class MutilineComment {    public static void main(String[] args) {        /*         * 这是一个多行注释         * 在控制台中显示"多行注释"字符串         * 巴拉巴拉         * // 多行注释中可以嵌套单行注释哦         */        System.out.println("多行注释");    }}

包含在“/**”和“*/”之间，也能注释多行内容，一般用在类、方法和变量上面，用来描述其作用。注释后，鼠标放在类和变量上面会自动显示出我们注释的内容，如图所示。

文档注释可以通过 Javadoc 命令把文档注释中的内容生成文档，并输出到 HTML 文件中，方便记录程序信息。还可以包含一个或多个 @ 标签，每个 @ 标签都在新的一行开始。

/** * @author Leung * @version 1.0 * @deprecated 这是一个展示文档注释的类 */public class DocumentAnnotation {    /**     * 程序的入口     * @param args     */    public static void main(String[] args) {        System.out.println("文档注释");    }}

idea中，点击 Tools --> Generate JavaDoc，选择需要生成文档的包或者类，即可在指定目录下生成文件，其中有一个index.html，打开即可看到。

这里给大家小结一下，在 Java 中，

Java支持3种注释，分别是单行注释、多行注释和文档注释。文档注释以/**开头，并以*/结束，可以通过 Javadoc 生成 API 帮助文档，Java 帮助文档主要用来说明类、成员变量和方法的功能。

文档注释只放在类、接口、成员变量、方法之前，因为 Javadoc 只处理这些地方的文档注释，而忽略其它地方的文档注释。

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

Javadoc标签

Javadoc 工具可以识别文档注释中的一些特殊标签，这些标签一般以@开头，后跟一个指定的名字，有的也以{@开头，以}结束。Javadoc 可以识别的标签如下表所示：

对两种标签格式的说明：

Javadoc 标签注意事项：

avadoc命令

Javadoc 用法格式如下：

javadoc [options] [packagenames] [sourcefiles]

对格式的说明：

在 cmd（命令提示符）中输入javadoc -help就可以看到 Javadoc 的用法和选项（前提是安装配置了JDK），下面列举 Javadoc 命令的常用选项：

DOS命令生成API帮助文档

新建一个空白记事本，输入下列代码：

/*** @author C语言中文网* @version jdk1.8.0*/public class Test{    /**     * 求输入两个参数范围以内整数的和     * @param n 接收的第一个参数，范围起点     * @param m 接收的第二个参数，范围终点     * @return 两个参数范围以内整数的和     */    public int add(int n, int m) {        int sum = 0;        for (int i = n; i <= m; i++) {            sum = sum + i;        }        return sum;    }}

将文件命名为 Test.java，打开 cmd 窗口，输入javadoc -author -version Test.java命令。

打开 Test.java 文件存储的位置，会发现多出了一个 Test.html 文档。

注意：以上没有考虑编码格式的问题，注释中有汉字可能会乱码。使用javadoc -encoding UTF-8 -charset UTF-8  Test.java会解决编码问题。

MyEclipse生成API帮助文档

1、在 MyEclipse 中新建一个 Test 类，代码如下：

package test;/*** @author C语言中文网* @version jdk1.8.0*/public class Test {    public static void main(String[] args) {        /**         * 这是一个输出语句         */        System.out.println("C语言中文网Java教程");    }}

注意：代码 9~11 行没有放在类、成员变量或方法之前，所以 Javadoc 会忽略这个注释。

2、在项目名处单击鼠标右键，然后选择Export...，所示。

3、在弹出窗口中选择 Java 文件夹，点击 Java 文件夹下面的 Javadoc，然后点击“Next”，如图所示。

4、选择你要生成 Javadoc 的项目，并更改你想保存的 API 帮助文档地址（默认为工程目录下，建议不要修改）。点击“Finish”，如图所示。

5、点击“Finish”之后会问是否更新 Javadoc 文件的位置，只需要点击“Yes To All”即可，如图所示。

6、这时可以看到控制台输出生成 Javadoc 的信息，如图所示。

7、打开保存的文件夹，找到 Test.html 文件并打开，如图所示。

以上就是使用 MyEclipse 简单建立一个 API 帮助文档的过程。

文档注释的格式

在编写文档注释的过程中，有时需要添加 HTML 标签，比如：需要换行时，应该使用<br>，而不是一个回车符；需要分段时，应该使用<p>。

例如把上面 Test 类改为以下代码：

package test;
/*** @author C语言中文网<br>* 严长生* @version 1.8.0<br>* 1.9.0*/public class Test {public static void main(String[] args) {System.out.println;}}

帮助文档格式如图所示。

Javadoc 并不是将代码中的文档注释直接复制到帮助文档的 HTML 文件中，而是读取每一行后，删除前面的*号及*以前的空格再输入到 HTML 文档。   

/*** first line.******* second line.* third line.*/

编译输出后的 HTML 源码如下所示。

first line. <br>second line. <br>third line.

注释前面的*号允许连续使用多个，其效果和使用一个*号一样，但多个*前不能有其他字符分隔，否则分隔符及后面的*号都将作为文档的内容。

Java注释的三种方式就讲解这么多，注释在编程中是很重要的一部分，最好在学习编程之初就养成写注释的好习惯，这样在以后的开发工作中会给你带来意想不到的好处哟！