Java 注释
单行注释:// 注释内容
多行注释:/* … 注释内容….*/
文本注释:/* * .. 注释内容…. */
文本注释:/* * .. 注释内容…. */
文本注释能够自动地生成文档。在JDK中有个javadoc的工具 ( 用法: javadoc [options] [packagenames] [sourcefiles] [@files] ),可以由源文件生成一个HTML文档。使用这种方式注释源文件的内容:专业,快速、有效、便于修改并且能够源文件的保存而保存起来。当修改源文件时,也可能对这个源代码的需求等一些注释性的文字进行修改,那么,这时候可以将源代码和文档一同保存,而不用再另外创建一个文档。
文档注释位置
(1)类注释。类注释用于说明整个类的功能、特性等,它应该放在所有的“import”语句之后,在class定义之前。
这个规则也适用于接口(interface)注释。
(2)方法注释。方法注释用来说明方法的定义,比如,方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。
(3)属性注释。默认情况下,javadoc只对公有(public)属性和受保护属性(protected)产生文档——通常是静态常量。
(4)包注释。类、方法、属性的注释都直接放到Java的源文件中,而对于包的注释,无法放到Java文件中去,只能通过在包对应的目录中添加一个package.html的文件来达到这个目的。当生成HTML文件时,package.html文件的和部分的内容将会被提取出来当做包的说明。关于包注释,后面还会有更进一步的解释。
(5)概要注释。除了包注释外,还有一种类型的文档无法从Java源文件中提取,就是对所有类文件提供概要说明的文件。同样的,也可以为这类注释单独新建一个HTML文件,这个文件的名字为“overview.html”,它的和标记之间的内容都会被提取。
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 |
代码中特殊注释——TODO、FIXME、XXX、HACK
TODO:英语翻译为待办事项,备忘录。如果代码中有该标识,说明在标识处有功能代码待编写,待实现的功能在说明中会简略说明。
FIXME:可以拆成短语,fix me ,意为修理我。如果代码中有该标识,说明标识处代码需要修正,甚至代码是错误的,不能工作,需要修复,如何修正会在说明中简略说明。
XXX:如果代码中有该标识,说明标识处代码虽然实现了功能,但是实现的方法有待商榷,希望将来能改进,要改进的地方会在说明中简略说明。
HACK:英语翻译为砍。如果代码中有该标识,说明标识处代码我们需要根据自己的需求去调整程序代码。
Eclipse中特殊的注释:
在Eclipse中,TODO、FIXME和XXX都会被Eclipse的task视图所收集。
在开发过程中在合适的位置添加合适的注释是非常有必要的,我们可以在任务完成前检查这些标记。
Window—>Show View—>Tasks