Java 之注释介绍

前言

Java 之 Annotation(注解)介绍

之前有写过一篇 Java 注解的介绍。参考以上链接。

虽然注解、注释只相差一个字，但是用法就差异很大。

总体一句话，注解给编译器看，注释是给人看的。

基于此的话，对于一个方法来说：

1. 把这个方法的作用，输入，输出描述清楚就可以了，更多的可以加上一些作者呀，版本呀这样一些信息

2. 注释编排的美观一些

做到这两点应该就可以了。举个例子：

 /******************************************************************************** NAME:         usage* DESCRIPTION: XXX* ARGUMENTS: N/A* RETURN:       * AUTHOR:        oscar999* VERSION:      V0.1*******************************************************************************/

看上去这是一个不错的注释^^.

但是对于Java 语言来说，注释被赋予了更多的功能。就是你可以使用javadoc 这个功能把代码中的注释导出到 html 的文件中。

如果你的代码是共用性很高的代码的话，这份文档就是一份API的参考文档，类似Java API.

所以，要产生出这样的文档，就要遵循java 定义的一些注释规范，才能产生出规范的文档出来。

Java 类方法的标准注释

还是从类的方法的注释说起。

    /*** Read a line of text.  A line is considered to be terminated by any one* of a line feed ('\n'), a carriage return ('\r'), or a carriage return* followed immediately by a linefeed.** @param      ignoreLF1  If true, the next '\n' will be skipped

     * @param      ignoreLF2  If true, the next '\n' will be skipped

     *     * @return     A String containing the contents of the line, not including     *             any line-termination characters, or null if the end of the     *             stream has been reached     *      * @see        java.io.LineNumberReader#readLine()     *     * @exception  IOException  If an I/O error occurs     */

（不去关注以上注释的意义，只关注其定义的样式）

1. 首先看最上面的 “Read a line of text. A line .. ” 这一段是对这个方法的一些描述。

第一个句号前面的部分，也就是 “Read a line of text.” 会出现在 “方法摘要” 中

全部的描述信息会出现在“ 方法详细信息” 中

2. @param 定义的是方法的输入参数，（可以添加多个）出现在“ 方法详细信息” 中。（参数和参数描述之间使用空格隔开，在产生的文档中转成了 -）

3. @return 返回值的描述

4. @see 参考的描述

5. @exception 异常抛出的描述

美观考虑，不同类的标签可以换一行显示，比如 @param 和 @return 直接空一行。

Java 类标准注释

类的注释和方法注释的格式基本相同。区别的地方：

1. 放置的位置不同。类的注释放在类定义的上面，方法的注释放在方法定义的上面。

2. 类的注释比较会使用 @version @author @since 这样的标签。

看模板

/** will buffer the input from the specified file.  Without buffering, each
* invocation of read() or readLine() could cause bytes to be read from the
* file, converted into characters, and then returned, which can be very
* inefficient.
*
*
* Test Description
*
* <p> Programs that use DataInputStreams for textual input can be localized by
* replacing each DataInputStream with an appropriate BufferedReader.
*
* @see FileReader
* @see InputStreamReader
*
* @version     0.1, 11/20/13
* @author  oscar999
* @since   JDK1.5
*/

doc 中显示的效果是：

同样，描述的第一句出现在“类概要”中。

类的详细信息显示如下：

值得注意的是 description 中<p> 的使用。如果没有加<p> , 在java code 中不管是否有换行，产生的doc 中都不换行。加上<p> 的话， doc 中出现换行。

补充

补充一下，产生javadoc的方法：

1. 命名行方式： javadoc + 参数

2. 使用Eclipse IDE 导出

如果在Eclipse IDE 中，在源文件或是项目上右键单击 , 选 Export --->

Java --> Javadoc 就可以产生了。