nybon 发表于 2005/2/5 21:09:16 |
以下是参考的一些文章:
How to Write Doc Comments for the Javadoc Tool
javadoc，在 Java 的注释上做文章
在java源码中为Javadoc编写文档注释(1)
500)this.width=500'> 在java编码规范中，提到了文档注释可被javadoc用来生成API文档。具体的写法，另有说明。下面是学习笔记，主要是摘了一些值得注意的要点。
1、javadoc的获取
只能从相应的JDK中取得，安装后在bin目录下。具体如下：* Javadoc 1.4 is included in Java 2 SDK, Standard Edition v 1.4* Javadoc 1.3 is included in Java 2 SDK, Standard Edition v 1.3* Javadoc 1.2 is included in Java 2 SDK, Standard Edition v 1.2* Javadoc 1.1 is included in JDK 1.1
2、文档注释编写(principles)
Java平台API文档由源码中的文档注释定义，且任何此类文档皆从此类注释取得
Java平台API文档是调用者(caller)和实现之间的契约(contract)
除非另有说明，Java平台API文档声明(assertion)应为与具体实现无关(implelementation-independent)
Java平台API文档应有足够的声明，以使得软件质量保证部门能写出完全的JCK (Java Compatibility Kit)测试。
3、文档注释编写细则
每个文档注释的第一句，应是个概要句，简明但无遗地描述API项。第一句在第一个后跟空格的点号前结束。当句中出现非结束意义的点加空格时，需要空格进行转义，如 等。
自动重利用父类/接口方法（method）的注释，当（1）一个类方法重写(override)父类的方法时，或（2）一个接口方法重写父接口的方法时，或（3）一个类方法实现一个接口方法时。如果当前方法没文档注释，则从父方法复制，如果有，则不复制而是前两者有小标题 "Overrides",后者有"Specified by".
用<code>...</code>来标注关键词或名字
节约使用行内链接{@link}
对方法和构建函数的说明，要去掉括号
可以为了简短使用短语而不是句子
使用第3人称而不是第2人称
以一个动词短语开始对一个方法的描述
对类/接口/字段(field)的描述，可以忽略主语
用"this"而不是“the"来引用从当前类生成的对象
不要仅是简单地把API名字里的单词展开来做描述，要增加一些信息。
当作用"field"一词时，注意它易引起混淆
避免拉丁语缩写
标签顺序
@author，多个作者时按参考修改代码的年代为序
@version
@param，多个参数时以方法声明中的顺序为序，单个@param后跟参数名（不要相应的类型），再加描述
@return
@exception，多个异常时以异常名字的字母顺序为序
@see，多个参见时据 #field,#Constructor(Type, Type...),#Constructor(Type id, Type id...),#method(Type, Type,...),#method(Type id, Type, id...),Class,Class#field,Class#Constructor(Type, Type...),Class#Constructor(Type id, Type id),Class#method(Type, Type,...),Class#method(Type id, Type id,...),package.Class,package.Class#field,package.Class#Constructor(Type, Type...),package.Class#Constructor(Type id, Type id),package.Class#method(Type, Type,...),package.Class#method(Type id, Type, id),package排序
@since
@serial
@deprcated
＠param和@return(当返回不是void时)都是必须的
|
.: 
