Java基础是java初学者的起点，是帮助你从小白入门到精通必学基础课程！

 为初学者而著！

Java300集>>>适合准备入行开发的零基础员学习Java，基于最新JDK13、IDEA平台讲解的，视频中穿插多个实战项目。每一个知识点都讲解的通俗易懂，由浅入深。不仅适用于零基础的初学者，有经验的程序员也可做巩固学习。

 配套学习：Java初学者入门教程>>>

Java注释：单行、多行和文档注释

注释是对程序语言的说明，有助于开发者和用户之间的交流，方便理解程序。注释不是编程语句，因此被编译器忽略。

Java支持以下三种注释方式：

1、单行注释

以双斜杠“//”标识，只能注释一行内容，用在注释信息内容少的地方。打开 Eclipse，在 Java 代码中使用单行注释，如图所示。

2、多行注释

包含在“/*”和“*/”之间，能注释很多行的内容。为了可读性比较好，一般首行和尾行不写注释信息（这样也比较美观好看），如图所示。

注意：多行注释可以嵌套单行注释，但是不能嵌套多行注释和文档注释。

3、文档注释

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

注意：文档注释能嵌套单行注释，不能嵌套多行注释和文档注释，一般首行和尾行也不写注释信息。

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

在 Java 中，一行注释以双斜杠“//”标识；

多行注释包含在“/*”和“*/”之间；

文档注释包含在“/**”和“*/”之间。

当编译器执行到“//”时，就会忽略该行“//”之后的所有文本；

当执行到“/*”时，会扫描下一个“*/”并忽略“/*”和“*/”之间的任何文本；

当执行到“/**”时，也会扫描下一个“*/”并忽略“/**”和“*/”之间的任何文本内容。

Javadoc（文档注释）详解

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

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

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

API 帮助文档相当于产品说明书，而说明书只需要介绍那些供用户使用的部分，所以 Javadoc 默认只提取 public、protected 修饰的部分。如果要提取 private 修饰的部分，需要使用 -private。

Javadoc标签

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

对两种标签格式的说明：

• @tag 格式的标签（不被{ }包围的标签）为块标签，只能在主要描述（类注释中对该类的详细说明为主要描述）后面的标签部分（如果块标签放在主要描述的前面，则生成 API 帮助文档时会检测不到主要描述）。
• {@tag} 格式的标签（由{ }包围的标签）为内联标签，可以放在主要描述中的任何位置或块标签的注释中。

Javadoc 标签注意事项：

• Javadoc 标签必须从一行的开头开始，否则将被视为普通文本。
• 一般具有相同名称的标签放在一起。
• Javadoc 标签区分大小写，代码中对于大小写错误的标签不会发生编译错误，但是在生成 API 帮助文档时会检测不到该注释内容。

avadoc命令

Javadoc 用法格式如下：

javadoc [options] [packagenames] [sourcefiles]

对格式的说明：

• options 表示 Javadoc 命令的选项；
• 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教程访问地址：http://c.biancheng.net/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("C语言中文网Java教程访问地址：http://c.biancheng.net/java/");
}
}

帮助文档格式如图所示。

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

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

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

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

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

小伙伴如果想要学习更多的知识，学习材料可以，工众号：编程领域

Java初学者学习教程：Java初学者入门教程>>>