在java源码中为Javadoc编写文档注释(1)

　　在 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"一词时，注意它易引起混淆

避免拉丁语缩写

标签顺序
1. @author，多个作者时按参考修改代码的年代为序
2. @version
3. @param，多个参数时以方法声明中的顺序为序，单个@param后跟参数名（不要相应的类型），再加描述
4. @return
5. @exception，多个异常时以异常名字的字母顺序为序
6. @see，多个参见时据#field,#Constructor(Type, Type...),#Constructor(Type id, Typeid...),#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, Typeid,...),package.Class,package.Class#field,package.Class#Constructor(Type,Type...),package.Class#Constructor(Type id, Typeid),package.Class#method(Type, Type,...),package.Class#method(Type id,Type, id),package排序
7. @since
8. @serial
9. @deprcated

＠param和@return(当返回不是void时)都是必须的

秒客网

在java源码中为Javadoc编写文档注释(1)

1、javadoc的获取

2、文档注释编写(principles)

3、文档注释编写细则

相关文章