注释：注释起到对代码标注和解释的作用，如果你去看看JDK源码，会发现他们有许多的注释，而且注释是比代码还要多的，可见为代码添加注释是非常重要的，写好注释能让别人更加容易看懂你的代码，注释可以分为以下三种。

使用//进行注释：

使用/**/进行注释：

使用/** */进行注释：

文档注释主要是用来生成java开发文档javadoc的，生成的开发文档和Java本身的API帮助文档是一样的，也就是对你所写的类进行解释说明，所以它还需要搭配一些文档标记，进行解释说明，而且在文档注释中可以使用HTML语言，jdk源码中有大量的文档注释，所以弄懂文档注释可以帮助你更好的看懂源码。

文档注释通常还会配合HTML标签进行使用，比较常用的标签有

等标签，p标签用于表示段落，pre标签可用于显示计算机源码。

注意：pre标签中如果有小于号、大于号、例如泛型 在生产javadoc时会报错。

以下文档标记在类、方法、变量和常量上都经常使用。

@link： 用于快速链接到相关代码，使用格式：{@link 包名.类名#方法名(参数类型)}

@code： 将文本标记为代码样式文本，一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记，使用格式：{@code text}，其会被解析为 text

@param：如果一个类支持泛型时，可以通过@param来解释泛型的类型

@author：用来标记作者，如果一段程序是由多个作者来维护，则可以标记多个@author,@author 后面可以跟作者姓名(也可以附带作者邮箱地址)、组织名称(也可以附带组织官网地址)

@see :另请参阅的意思，一般用于标记与本类相关联的类，该标注可以用在类或方法上。

@since：表示从以下版本开始有这个类，标记文件创建时项目当时对应的版本，后面可以跟版本号或是时间。

@version：用于标记当前类版本，默认为1.0

以上是类上常用的文档标注，类上的文档格式如下：

以下是String类的中文档标注的事例：

* Strings are constant; their values cannot be changed after they * are created. String buffers support mutable strings. * Because String objects are immutable they can be shared. For example: * * String str = "abc"; *

* is equivalent to: * * char data[] = {'a', 'b', 'c'}; * String str = new String(data); *

* Here are some more examples of how strings can be used: * * System.out.println("abc"); * String cde = "cde"; * System.out.println("abc" + cde); * String c = "abc".substring(2,3); * String d = cde.substring(1, 2); * *

* The class {@code String} includes methods for examining * individual characters of the sequence, for comparing strings, for * searching strings, for extracting substrings, and for creating a * copy of a string with all characters translated to uppercase or to * lowercase. Case mapping is based on the Unicode Standard version * specified by the {@link java.lang.Character Character} class. *

* The Java language provides special support for the string * concatenation operator (;+;), and for conversion of * other objects to strings. For additional information on string * concatenation and conversion, see The Java™ Language Specification. * *

Unless otherwise noted, passing a {@code null} argument to a constructor * or method in this class will cause a {@link NullPointerException} to be * thrown. * *

A {@code String} represents a string in the UTF-16 format * in which supplementary characters are represented by surrogate * pairs (see the section Unicode * Character Representations in the {@code Character} class for * more information). * Index values refer to {@code char} code units, so a supplementary * character uses two positions in a {@code String}. *

The {@code String} class provides methods for dealing with * Unicode code points (i.e., characters), in addition to those for * dealing with Unicode code units (i.e., {@code char} values). * *

Unless otherwise noted, methods for comparing Strings do not take locale * into account. The {@link java.text.Collator} class provides methods for * finer-grain, locale-sensitive String comparison. * * @implNote The implementation of the string concatenation operator is left to * the discretion of a Java compiler, as long as the compiler ultimately conforms * to The Java™ Language Specification. For example, the {@code javac} compiler * may implement the operator with {@code StringBuffer}, {@code StringBuilder}, * or {@code java.lang.invoke.StringConcatFactory} depending on the JDK version. The * implementation of string conversion is typically through the method {@code toString}, * defined by {@code Object} and inherited by all classes in Java. * * @author Lee Boynton * @author Arthur van Hoff * @author Martin Buchholz * @author Ulf Zibis * @see java.lang.Object#toString() * @see java.lang.StringBuffer * @see java.lang.StringBuilder * @see java.nio.charset.Charset * @since 1.0 * @jls 15.18.1 String Concatenation Operator + */ public final class String implements java.io.Serializable, Comparable, CharSequence { } （3）方法上常用文档标记

@param：该文档标记后面写方法的参数名，再写参数描述。

@return：该文档标记后面写返回值得描述。

@throws：该文档标记后面写异常的类型和异常的描述，用于描述该方法可能抛出的异常。

@exception：该标注用于描述方法签名throws对应的异常。

@see：可用在类与方法上，表示参考的类或方法。

以上是方法上常用的文档标注，方法上的文档格式如下：

以下是String类中charAt方法的示例：

If the {@code char} value specified by the index is a * surrogate, the surrogate * value is returned. * * @param index the index of the {@code char} value. * @return the {@code char} value at the specified index of this string. * The first {@code char} value is at index {@code 0}. * @exception IndexOutOfBoundsException if the {@code index} * argument is negative or not less than the length of this * string. */ public char charAt(int index) {} （4）变量和常量上的文档规范

变量和常量上用的比较多的文档标记是@link和@code，主要注释该常量或变量的基本用法和相关内容。

以下是示例：

首先先展示下我写的文档注释代码：

HelloWorld.java

这是一个测试javadoc的类 * * @author codepeace * @version 1.0 * @since 1.8 * */ public class HelloWorld { String name; /** * * @param name * @return name * @throws Exception * {@code name} */ public String test(String name)throws Exception{ return name; } }

Doc.java

这是一个测试javadoc的类 * * @author codepeace * @version 1.0 * @since 1.8 * */ public class Doc { String name; /** * * @param name * @return name * @throws Exception * {@code name} */ public String test(String name)throws Exception{ return name; } } （1）使用命令行的方式 用wiodow打开cmd终端，然后进入要编译的java文件目录的路径中，如下所示： image 输入命令：javadoc -encoding UTF-8 -charset UTF-8 *.java，就能将你的java文件编译成帮助文档。 -encoding 是编码格式， -charset是字符集格式，需要查看你文件的编码格式，可以通过打开记事本查看编码格式。 image image 编译成功后你后发现当前路径下会多出很多文件，我们需要的文件是index.html文件。 image 点开后为如下样式，至此帮助文档生成完毕。 image （2）使用IDE工具的方式 使用idea生成javadoc文档 打开 idea，点击 Tools-> Generate JavaDoc，这样会打开生成 javadoc 文档的配置页面。 image 配置javadoc文档输出详情： 选择要输出文档的范围，选择是整个项目还是模块还是单个文件。 文档要输出路径。 选择哪些类型的方法或参数可以生成文档。 Locale 选择地区，这个决定了文档的语言，中文就是zh_CN。 传入JavaDoc的参数，一般写 -encoding UTF-8 -charset UTF-8，表示编码格式。 image 点击确定，运行无误后，打开你所选择的文档输出路径后，选择index.html，就是所输出的javadoc文档。 image image 使用eclipse生成javadoc文档 打开eclipse，点击 Project-> Generate JavaDoc，这样会打开生成 javadoc 文档的配置页面。 image 配置以下javadoc文档输出详情，后点击next 选择要输出成文档的文件或模块 选择哪些类型的方法或参数可以生成文档 文档要输出路径。 image 设置文档名后，点击next image 设置编码格式 一般写-encoding UTF-8 -charset UTF-8，设置jre版本，然后点击完成，在刚才设置的输出路径中找到index.html即可。 image

注意点：eclipse的默认编码不是UTF-8，所以要将其修改为UTF-8，修改方法如下：

打开eclipse，点击 Window-> Preferences->Workspace，将默认的GBK编码改为UTF-8即可。

更多精彩内容敬请关注微信公众号：【平兄聊Java】