活动地址：CSDN21天学习挑战赛
（一）注释的重要性
编写程序的时候，总需要为程序添加一些注释，用以说明某段代码的作用，或者说明某个类的用途，某个方法的工能，以及该方法的的参数和返回值的数据类型以及意义等
程序注释的作用非常大，很多初学者在刚刚学习java程序的时候，会很努力的写程序，不太会注意添加注释。认为添加注释是一种浪费时间，没有意义的事情。经过一段时间的学习，注意到程序书写的不足，需要重构。于是打开源码，以为可以很轻松的改写原有代码，但这个时候会发现理解原来写的代码会非常的困难，很难理解原有的编程思路。
为什么需要添加注释，至少有如下三方面的考虑：
1 永远不要过于相信自己的理解能力：
2 可读性第一，效率第二！
3 代码即文档：
程序注释是源代码的一个重要部分，对于一份规范的程序源代码而言，注释应该占到源代码的三分之一以上。几乎所有的编程都提供了注释的方法，一般包括，单行注释，多行注释。java语言也不例外，不仅包括单行注释，多行注释，还提供了一种文档注释。java语言的注释一共有三种类型。
（二）java的三种注释
单行注释：在程序中注释一行代码
多行注释：一次性的将程序中多行代码注释掉。
文档注释：注释允许你在程序中嵌入关于程序的信息。
（三）单行注释，多行注释
单行注释：将双斜线//放到需要注释的内容之前就可以了。
多行注释：使用/* 和 */ 将程序中需要注释的内容包含起来。
/* 表示注释的开始 */ 表示注释的结束。
（四）增强文档注释
java还提供了一种功能更强大的注释形式，文档注释。它以 /** 开始，以 */结束。例子如下：
- /***
- * 这是一个注释
- * @author alan
- * @version 1.2
- */
如果编写java源代码的过程中添加了文档注释吗，然后通过JDK提供的javac工具可以直接将源代码里的文档注释提取程一份系统的API文档。
javadoc 工具软件识别以下标签：
| 标签 | 描述 | 示例 |
|---|---|---|
| @author | 标识一个类的作者 | @author description |
| @deprecated | 指名一个过期的类或成员 | @deprecated description |
| {@docRoot} | 指明当前文档根目录的路径 | Directory Path |
| @exception | 标志一个类抛出的异常 | @exception exception-name explanation |
| {@inheritDoc} | 从直接父类继承的注释 | Inherits a comment from the immediate surperclass. |
| {@link} | 插入一个到另一个主题的链接 | {@link name text} |
| {@linkplain} | 插入一个到另一个主题的链接，但是该链接显示纯文本字体 | Inserts an in-line link to another topic. |
| @param | 说明一个方法的参数 | @param parameter-name explanation |
| @return | 说明返回值类型 | @return explanation |
| @see | 指定一个到另一个主题的链接 | @see anchor |
| @serial | 说明一个序列化属性 | @serial description |
| @serialData | 说明通过writeObject( ) 和 writeExternal( )方法写的数据 | @serialData description |
| @serialField | 说明一个ObjectStreamField组件 | @serialField name type description |
| @since | 标记当引入一个特定的变化时 | @since release |
| @throws | 和 @exception标签一样. | The @throws tag has the same meaning as the @exception tag. |
| {@value} | 显示常量的值，该常量必须是static属性。 | Displays the value of a constant, which must be a static field. |
| @version | 指定类的版本 | @version info |
javadoc 输出什么?
javadoc 工具将你 Java 程序的源代码作为输入，输出一些包含你程序注释的HTML文件。
每一个类的信息将在独自的HTML文件里。javadoc 也可以输出继承的树形结构和索引。
由于 javadoc 的实现不同，工作也可能不同，你需要检查你的 Java 开发系统的版本等细节，选择合适的 Javadoc 版本。