我们知道在java中注释有三种，第一种，单行注释 //注释的内容，第二种，多行注释 /*…注释的内容…*/，第三种 文档注释 /**..注释的内容….*/。不难发现，第三种注释方式和第二种方式很相似，那它出现的目的是什么呢？就是为了便于javadoc程序自动生成文档。接下来咱们聊一聊这个文档注释⋯⋯

添加注释的原则

代码注释是架起程序设计者与程序阅读者之间的通信桥梁，最大限度的提高团队开发合作效率，也是程序代码可维护性的重要环节之一。所以看起来非常简单的注释也是有些原则需要遵守：

1、注释形式统一

在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同，按照这份规范写代码，不要试图在既成的规范系统中引入新的规范。

2、注释内容准确简洁

内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。

注释可以添加的位置

作为注释，语法上当然是可以添加在程序的任意位置啦！但是我们在添加时候还是要添加在合适的位置，一般添加在类和方法上。如下图所示：

大家仔细看，可以发现注释中有这些东西@author，@version，@see，@param ⋯⋯，这些都是什么含义呢？

这些都称之为java doc标记，含义如下：

@author 标明开发该类模块的作者

@version 标明该类模块的版本

@see 参考转向，也就是相关主题

@param 对方法中某参数的说明

@return 对方法返回值的说明

@exception 对方法可能抛出的异常进行说明

其中，@author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次，只有第一次有效。@param、@return 和 @exception 这三个标记都是只用于方法的。

把注释生成文档的方式

通常在编写程序时我们会用IDE工具，比如eclipse，咱们来看看怎么用eclipse生成文档。如下图：

第一步：

下一步：

下一步：

接着点finish就好啦，可能在点finish的时候弹出一个框，直接选择”yes to all”就好了！找到我的E：\myapi文件夹，会发现生成了很多文件：

用浏览器打开你就看到自己想要的东西了！

说完这个，咱们再说说如何用doc生成文档：

看图：

参数说明

-public 仅为public访问级别的类及类的成员生成javaDoc文档

-proteceted 仅为public和protected访问级别的类及类的成员生成javadoc文档.

(默认选项)

-d 指定API文档的输出目录，默认是当前目录。建议总是指定该参数。

然后找到E:\mydosapi文件夹，打开index.html就看到文档已经生成好了⋯⋯

好了，java文档注释就说到这里，如果还有不明白的，那就自行体会，哈哈⋯⋯