Java文档注释

什么是Java文档注释？

Java文档注释是使用特殊的文档格式将文档内容写在代码中，然后可以使用Javadoc将这些文档提取出来，这样就避免了我们在写代码的过程中还要切换到其他软件中写文档的麻烦。javadoc输出的是一个HTML文档，可以使用Web浏览器来查看，这也意味着我们可以在文档注释中使用HTML语法。

如何写Java文档注释？

Java文档注释是以/**为开始符号，以*/结尾的一段内容：

/**
 * This is the way to test it
 *
 * @param  b  The byte to be written
 * @param  buf   A byte array
 * @return {@code true} if and only if this stream has encountered an
 * @throws  NullPointerException  If {@code s} is {@code null}
 * @see #print(char)
 * @see #println(char)
*/

注意：

1. 在一些编辑器，如Eclipse中，敲入/**后按下Enter键会自动生成文档注释
2. 文档注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。

Java文档注释的内容

Java文档注释由两部分组成，描述部分和标记部分。描述部分就是用一段简短的话对这个类或方法等做一个概要的描述。标记部分就是@param, @return, @see之类。下面是一个例子：

/**
 *
 * <p> An invocation of this method of the form {@code out.append(csq)}
 * behaves in exactly the same way as the invocation
 *
 * <pre>{@code
 *     out.print(csq.toString())
 * }</pre>
 *
 * <p> Depending on the specification of {@code toString} for the
 * character sequence {@code csq}, the entire sequence may not be
 * appended.  For instance, invoking then {@code toString} method of a
 * character buffer will return a subsequence whose content depends upon
 * the buffer's position and limit.
 *
 * @param  b  The byte to be written
 * @param  buf   A byte array
 * @return {@code true} if and only if this stream has encountered an
 * @throws  NullPointerException  If {@code s} is {@code null}
 * @see #print(char)
 * @see #println(char)
*/

你可以很清楚的看出，@param之前的部分都是描述部分，带有@的行都是标记部分。

描述部分

描述部分是用来对这个方法或类等做一个概要的描述，描述应当能够简要说明要描述目标的功能特点等。另外，描述部分可以使用HTML语法来使得内容更加工整、有条理。

/**
 * Terminates the current line by writing the line separator string.  The
 * line separator string is defined by the system property
 * {@code line.separator}, and is not necessarily a single newline
 * character ({@code '\n'}).
*/

标记部分

标记部分跟在描述部分之后，且前面必须有一个空行间隔，

标记名	作用	注意事项
@author	表名类的作者	只能用在类的标记文档中，按照时间顺序排列，即原始作者要排在前面
@version	表名类的当前版本	只能用在类的标记文档中
@param	表名方法的参数	只能用在方法标记文档中，如果方法没有输入参数，可以省略，如果有多个输入参数，要按照方法中输入参数的顺序进行排列
@return	表名方法返回的参数	只能用在方法标记文档中，如果方法没有输出值，可以省略
@throws	表名方法或类抛出的异常	不抛出异常可以省略，抛出多个异常按照异常名称的首字母排列
@see	引用其他类中的文档
@since	表名这个方法或类在哪个版本时添加的	比@since更常用
@deprecated	表名这个方法已经被更新好的方法替代或被抛弃，不建议使用	在代码中使用被@deprecated标记的方法会收到编译器的警告

类、变量、方法文档标记

类文档标记

/**
 * A {@code PrintStream} adds functionality to another output stream,
 * namely the ability to print representations of various data values
 * conveniently.  Two other features are provided as well.  Unlike other output
 * streams, a {@code PrintStream} never throws an
 * {@code IOException}; instead, exceptional situations merely set an
 * internal flag that can be tested via the {@code checkError} method.
 * Optionally, a {@code PrintStream} can be created so as to flush
 * automatically; this means that the {@code flush} method is
 * automatically invoked after a byte array is written, one of the
 * {@code println} methods is invoked, or a newline character or byte
 * ({@code '\n'}) is written.
 *
 * <p> All characters printed by a {@code PrintStream} are converted into
 * bytes using the given encoding or charset, or platform's default character
 * encoding if not specified.
 * The {@link PrintWriter} class should be used in situations that require
 *  writing characters rather than bytes.
 *
 * <p> This class always replaces malformed and unmappable character sequences with
 * the charset's default replacement string.
 * The {@linkplain java.nio.charset.CharsetEncoder} class should be used when more
 * control over the encoding process is required.
 *
 * @author     Frank Yellin
 * @author     Mark Reinhold
 * @since      1.0
 */

注意：类文档标记部分要按照@author、@since/@version的顺序来排列

变量文档标记

变量标记中只能有描述部分和@see标记

例如：

/**
 * The "standard" output stream. This stream is already
 * open and ready to accept output data. Typically this stream
 * corresponds to display output or another output destination
 * specified by the host environment or user.
 * <p>
 * For simple stand-alone Java applications, a typical way to write
 * a line of output data is:
 * <blockquote><pre>
 *     System.out.println(data)
 * </pre></blockquote>
 * <p>
 * See the {@code println} methods in class {@code PrintStream}.  
 * @see     java.io.PrintStream#println(double)
 * @see     java.io.PrintStream#println(float)
 * @see     java.io.PrintStream#println(int)
 * @see     java.io.PrintStream#println(long)
 * @see     java.io.PrintStream#println(java.lang.Object)
 * @see     java.io.PrintStream#println(java.lang.String)
*/
    public static final PrintStream out = null;

方法文档标记

/**
 *
 * <p> An invocation of this method of the form {@code out.append(csq)}
 * behaves in exactly the same way as the invocation
 *
 * <pre>{@code
 *     out.print(csq.toString())
 * }</pre>
 *
 * <p> Depending on the specification of {@code toString} for the
 * character sequence {@code csq}, the entire sequence may not be
 * appended.  For instance, invoking then {@code toString} method of a
 * character buffer will return a subsequence whose content depends upon
 * the buffer's position and limit.
 *
 * @param  b  The byte to be written
 * @param  buf   A byte array
 * @return {@code true} if and only if this stream has encountered an
 * @throws  NullPointerException  If {@code s} is {@code null}
 * @see #print(char)
 * @see #println(char)
*/
public ......{
    
}

注意：

1. 类文档标记中的标记部分中要按照@param、@return、@throws、@since、@see、@deprecated的顺序进行排列
2. @return后面直接写的是对返回值的介绍，而没有返回变量名