JavaDoc注释与帮助说明文档

我们知道在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文档注释就说到这里,如果还有不明白的,那就自行体会,哈哈⋯⋯