在Java源代码中为Javadoc编写文档注释

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＂.

用...来标注关键词或名字

节约使用行内链接{@link}

对方法和构建函数的说明，要去掉括号

可以为了简短使用短语而不是句子

使用第3人称而不是第2人称

以一个动词短语开始对一个方法的描述

对类/接口/字段(field)的描述，可以忽略主语

用"this"而不是＂the＂来引用从当前类生成的对象

不要仅是简单地把API名字里的单词展开来做描述，要增加一些信息。

当作用＂field＂一词时，注意它易引起混淆

避免拉丁语缩写

标签顺序

@author，多个作者时按参考修改代码的年代为序

@version

@param，多个参数时以方法声明中的顺序为序，单个@param后跟参数名（不要相应的类型），再加描述

@return

@exception，多个异常时以异常名字的字母顺序为序

@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, 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时)都是必须的．