javaDoc注释与帮助说明文档
在Java开发过程中,保持来好的编码习惯,规范的书写注释,能够架起程序设计者与程序阅读者之间的桥梁,最大限度的提高团队开发合作效率,也是程序代码可维护性的重要环节。
注释
在java中一共有三种不同的注释,第一种,单行注释,//注释的内容,第二种,多行注释 ,/* …注释内容…* /,第三种 文档注释 ,/**…注释内容….*/。
单行注释,可添加在任意位置,不过本行//后面的内容都会视为注释内容,不被编译。
多行注释,由于可以以 / *开始直到 * /结束,可以跨行,代码写在里面也会被视为注释
文档注释, 由/ ** 和 * /将 注释内容括起来,一般在类和方法上面。与多行注释有一定的相似,但文档注释中有这些特殊的东西@author,@version,@see,@param ⋯⋯。
这些都称之为java doc标记,含义如下:
@author 标明开发该类模块的作者
@version 标明该类模块的版本
@see 参考转向,也就是相关主题
@param 对方法中某参数的说明
@return 对方法返回值的说明
@exception 对方法可能抛出的异常进行说明
标记还有更多不一一列举了
这些标记就是用来javadoc程序自动生成文档的,每个标记后面的类容会被填在文档相应的位置。
添加注释的原则
1、注释形式统一
在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范。
2、注释内容准确简洁
内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。
把注释生成文档的方式
在我们常用的eclipse中可以通过,export—>选择javadoc,选好选项后点finish就好,在预选的文件夹中就可以看见生成的东西了
同样我们也可以使用java自带的javadoc.exe来生成文档:通过 javadoc -public -d 保存地址 包名 类名 的形式来生成。