niyue

编写Javadoc

In java, programming on February 5, 2005 at 1:09 PM

以下是参考的一些文章:

  1. How to Write Doc Comments for the Javadoc Tool
  2. javadoc,在 Java 的注释上做文章
  3. 在java源码中为Javadoc编写文档注释(1)

v4_java_logo.gif  在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、文档注释编写细则

  1. 每个文档注释的第一句,应是个概要句,简明但无遗地描述API项。第一句在第一个后跟空格的点号前结束。当句中出现非结束意义的点加空格时,需要空格进行转义,如 等。
  2. 自动重利用父类/接口方法(method)的注释,当(1)一个类方法重写(override)父类的方法时,或(2)一个接口方法重写父接口的方法时,或(3)一个类方法实现一个接口方法时。如果当前方法没文档注释,则从父方法复制,如果有,则不复制而是前两者有小标题 “Overrides”,后者有”Specified by”.
  3. 用<code>…</code>来标注关键词或名字
  4. 节约使用行内链接{@link}
  5. 对方法和构建函数的说明,要去掉括号
  6. 可以为了简短使用短语而不是句子
  7. 使用第3人称而不是第2人称
  8. 以一个动词短语开始对一个方法的描述
  9. 对类/接口/字段(field)的描述,可以忽略主语
  10. 用”this”而不是“the”来引用从当前类生成的对象
  11. 不要仅是简单地把API名字里的单词展开来做描述,要增加一些信息。
  12. 当作用”field”一词时,注意它易引起混淆
  13. 避免拉丁语缩写
  14. 标签顺序
    1. @author,多个作者时按参考修改代码的年代为序
    2. @version
    3. @param,多个参数时以方法声明中的顺序为序,单个@param后跟参数名(不要相应的类型),再加描述
    4. @return
    5. @exception,多个异常时以异常名字的字母顺序为序
    6. @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排序
    7. @since
    8. @serial
    9. @deprcated
  15. @param和@return(当返回不是void时)都是必须的
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: