前言
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 + 参数
