Java的三种注释，和文档注释的生成文档说明

一、单行注释

二、多行注释

三、文档注释

---

编写注释的原因

编写程序时总需要为程序添加一些注释，用以说明某段代码的作用，或者说明某个类的用途、某个方法的功能，以及该方法的参数和返回值的数据类型及意义等。

编写注释的原因及意义如下：

1. 为了更好的阅读自己编写的代码，建议添加这注释。自己写的代码，可能过一段时间回顾的时候，就变得不熟悉。这个时候，注释就起到了很好的帮助作用。
2. 可读性第一，效率第二。一个软件一般都是一个团队协同作战开发出来的。因此，一个人写的代码，需要被整个团队的其他人所理解。
3. 代码即文档。程序源代码是程序文档的重要组成部分。

---

注释的语法规则

编写Java中的注释不会出现在可执行程序中。因此，可以在源程序中根据需要添加任意多的注释，而不必担心可执行代码会膨胀。在 Java 中，有三种书写注释的方式。

• 单行注释
• 多行注释
• 文档注释

下面分别详细的介绍这三种注释。

---

一、单行注释

是最常用的注释方式，其注释内容从 "//"开始到本行末尾。

---

二、多行注释

注释内容放到 "/*" 和 "*/"之间。也即是，注释从 "/*" 开始，到 "*/" 结束。

---

三、文档注释

/**......*/，这种方式和第二种方式相似。这种格式是为了便于javadoc程序自动生成文档。

下面介绍一下Javadoc的标记：

JavaDoc 标记	解释
@version	指定版本信息
@since	指定最早出现在哪个版本
@author	指定作者
@see	生成参考其他的JavaDoc文档的连接
@link	生成参考其他的JavaDoc文档，它和@see标记的区别在于，@link标记能够嵌入到注释语句中，为注释语句中的特殊词汇生成连接。  eg.{@link Hello}
@deprecated	用来注明被注释的类、变量或方法已经不提倡使用，在将来的版本中有可能被废弃
@param	描述方法的参数
@return	描述方法的返回值
@throws	描述方法抛出的异常，指明抛出异常的条件

javadoc标记：是@开头的，对javadoc而言，特殊的标记。

简单的一个语句：

javadoc -d docs FirstSample.java

这样子会在那个.java 文件的同目录下产生一个 docs 文件夹，里面会有很多html格式的文件，打开 index.html 即可查看文档注释。 

 

注意：

如果源文件中有用到@version,@author标记，则在执行javadoc命令时，要加-version -author 

javadoc -version -author -d doc *.java

（其中用-version用于提取源文件中的版本信息 -author用于提取源文件中的作者信息）