java文档注释规范（一）

Javadoc工具将从四种不同类型的“源”文件生成输出文档：Java语言类的源文件（.java），包注释文件，概述注释文件和其他未处理的文件。

包注释文件（Package Comment File）

每个包都有自己的文档注释。有两种方式来创建包注释文件：

package-info.java - 可以包含包的声明，包注解（anotation），包注释和Javadoc 标签（tag）。包注释放在包声明之前。这是JDK 5.0新引入的特性。如下。

File: java/applet/package-info.java  注意：文档注释块内部行首的*号是可选的

/**
 * Provides the classes necessary to create an applet and the classes an applet uses 
 * to communicate with its applet context. 
 * 

 * The applet framework involves two entities: 
 * the applet and the applet context. An applet is an embeddable window (see the 
 * {@link java.awt.Panel} class) with a few extra methods that the applet context 
 * can use to initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

package.html - 只能包含包注释和Javadoc标签，不能包含包注解。注释包含在元素内部。
注意：只能包含其中一个文件，如果同时包含两个文件，则 package.html 将被忽略。如下。

File: java/applet/package.html

Provides the classes necessary to create an applet and the classes an applet uses 
to communicate with its applet context. 

The applet framework involves two entities: 
the applet and the applet context. An applet is an embeddable window (see the 
{@link java.awt.Panel} class) with a few extra methods that the applet context 
can use to initialize, start, and stop the applet.

@since 1.0
@see java.awt

包注释的第一句应该对包进行概括。Javadoc tool 将会将这句话作为summary statement.对于包注释内容的具体书写可以参考：How to Write Doc Comments for Javadoc

javadoc工具将会以如下方式处理包注释文件：

• 复制注释并进行处理（对于package.html，复制和 HTML标记之间的所有内容）。
• 处理注释中存在的包标签。
• 将处理后的文本插入生成的包摘要页面的底部，参见java api 文档格式。
• 将包注释的第一句复制到包摘要页面的顶部。 并将包名称和第一个句子添加到概述页面上的包列表中。

概述注释文件（Overview Comment File）

Javadoc工具将由它生成概述页面。可以将概述注释文件命名为任何名称（一般命名为overview.html）并放在任何位置（通常放在source tree的顶层）。例如，如果java.applet包的源文件包含在C：\ user \ src \ java \ applet目录中，则可以将概述注释文件创建为C：\ user \ src \ overview.html。

概述注释文件的内容也是HTML编写的大文件注释，类似于包注释文件。注释的第一个句子作为应用程序或包集合的摘要，不要在和第一个句子之间放置标题或任何其他文本。除了内嵌标签（例如{@link}）之外的所有标签必须出现在主要描述之后。如果应用@see标签，则必须用fully-qualified name。

运行Javadoc工具时，使用-overview选项指定概述注释文件名。javadoc工具处理该文件的方式类似于包注释文件的处理。

• 复制和标记之间的所有内容并进行处理。
• 处理注释中存在的概述标签。
• 将处理后的文本插入生成的概述页面的底部。
• 将概述注释的第一句复制到概述摘要页面的顶部。

其他未处理的文件（Miscellaneous Unprocessed Files）

可以在源文件中包含任何杂项文件（由Javadoc工具复制到目标目录）。通常包括图像文件，Java示例源代码（.java）和类（.class）文件，独立的HTML文件。
未处理的文件应放在包含源文件的任何包目录下，名为doc-files的目录中。可以包括图像，示例代码，源文件，.class文件，applet和HTML文件。例如，如果要在java.awt.Button类文档中包含按钮button.gif的图像，则将该文件放在/ home / user / src / java / awt / doc-files /目录中。请注意，doc-files目录不应位于/ home / user / src / java / doc-files中，因为java目录不直接包含任何源文件。

这些未处理文件的所有链接都必须是硬编码的，因为Javadoc工具只是将目录及其所有内容复制到目标。例如，Button.java doc注释中的链接可能如下所示：

  /**
    *此按钮如下所示：
    * 
    */

测试文件和模板文件

一些开发人员表示他们希望将源代码树中的测试文件和模板文件存储在相应的源文件附近。也就是说，他们希望将它们放在这些源文件的同一目录或子目录中。
如果通过显式传入单个源文件名来运行Javadoc工具，则可以故意忽略测试和模板文件以防止它们被处理。但是，如果要传递包名称或通配符来运行Javadoc工具，则需要遵循某些规则以确保不处理这些测试文件和模板文件。

测试文件与模板文件的不同之处在于前者是合法的，可编译的源文件，而后者不是，但可能以“.java”结尾。

可以将测试文件放在子目录中（该子目录是一个无效的包名）。例如，如果要在com.package1中为源文件添加测试文件：

   com/package1/test-files/
Javadoc工具将跳过测试目录，没有任何警告。
如果您的测试文件包含doc注释，则可以设置单独的Javadoc工具运行，以通过传入带有通配符的测试源文件名来生成测试文件的文档，例如com / package1 / test-files / * .java。

源文件的模板文件的名称通常以“.java”结尾，并且不可编译。如果您有要保留在源目录中的源文件的模板，则可以使用短划线（例如Buffer-Template.java）或任何其他非法Java字符命名，以防止对其进行处理。

Java源文件中的文档注释

注释的位置：文档注释仅紧接放置在类，接口，构造函数，方法或字段声明之前。放置在方法体中的文档注释将被忽略。 

文档注释由主要描述部分 + 标签部分组成：主要描述在起始分隔符/ **之后开始，一直到标签部分。 标签部分以第一个块标签开始，块标记由一个@字符定义（忽略前导 *，空格和前导分隔符/ **）。 可以只有标签部分而没有主要描述部分。 标签部分开始后，不能续接主要描述部分。 标签的参数可以跨越多行。 可以有任意数量的标签：某些类型的标签可以重复，而其他标签则不能重复。 例如，这个@see标签部分：

/**
 * This sentence would hold the main description for this doc comment.
 * @see java.lang.Object
 */

块标签和内嵌标签。

有两种标签：块标签（显示为@tag（也称为“独立标签”））和内嵌标签（显示在花括号内）为{@tag}。块标签必须出现在行的开头，忽略前导 *，空格和分隔符（/ **）。 这意味着可以在文本的其他位置使用@字符，而不会被解释为标签的开始。 如果要以@字符作为一行的开始（非标签的开始），请使用HTML实体 @。 每个块标签都有关联的文本，包括标签之后的任何文本，直到下一个标签或文档注释的结尾。关联文本可以跨越多行。在允许文本的任何地方允许放置内嵌标签。 以下示例包含块标签@deprecated和内嵌标签{@link}。

/**
 * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
 */

注释以HTML格式编写：文本必须用HTML编写，应该使用HTML实体并且可以使用HTML标签。 例如，小于（<）和大于（>）符号应该写为＆lt; 和＆gt;。 同样，＆符号应该写成＆amp;  以下示例中显示了粗体HTML标记。

/**
 * This is a doc comment.
 * @see java.lang.Object
 */

前导 * ：每行上的前导星号（*）字符是可选的。从1.4开始，如果省略行上的前导星号，则不再删除前导空格。这使您可以将代码示例直接粘贴到

标记内，并且可以遵循其缩进。浏览器通常更加统一地解释空格。注意，缩进是相对于左边距（而不是分隔符/ **或
标记）。
 
  
 每个文档注释的第一句应该是一个简短的句子，包含对已声明实体的简明但完整的描述。这句话在第一个句点处结（后面紧跟空格，制表符或行终止符），或者在第一个块标签前结束。 Javadoc工具将第一个句子复制到HTML页面顶部的成员摘要中。
 
  
Java允许在单个语句中声明多个字段，但此语句只能有一个文档注释。因此，如果您需要为每个字段添加单独的文档注释，则必须分别声明每个字段。例如，以下文档注释没有意义，应当作为两个字段声明处理：
 
  
/** 
 * The horizontal and vertical distances of point (x,y)
 */
public int x, y;      // Avoid this  
 
  
在为成员（members）编写文档注释时，最好不要使用HTML标题标签，例如
和
。因为Javadoc工具会创建整个结构化的文档，而这些标题标签可能会影响对生成文件的格式化 。不过，可以在类和包注释中使用这些标题标签。
 
  
自动复制方法注释
 
  
Javadoc工具能够在以下两种情况下复制或“继承”类和接口中的方法注释。注意：构造函数，字段和嵌套类不继承文档注释。
  当方法注释中缺少一个主要描述或@return，@ param或@throws标签时，Javadoc工具从其所重写或实现的方法中复制相应的主要描述或标签注释（如果有的话）。（复制算法见下述：用于继承方法注释的算法）
 更具体地说，当缺少某个特定参数的@param标签时，将从继承层次结构中的方法复制该参数的注释。如果缺少某个特定异常的@throws标签，则仅在该异常已被声明时才复制@throws标签。此行为与1.3版本及更早版本形成相违背（其中，任何主要描述或标签的存在将阻止所有注释被继承）。
 
  
显式继承-在方法主要描述或@return，@ param或@throws标签注释中插入内联标记{@inheritDoc} ， 相应的主要描述或标签注释将复制到该方法。被继承的方法所在的源文件只需要在-sourcepath指定的路径上，以便文档注释可用于实际的复制。无论是类还是其包都不需要在命令行中传入。这与1.3.x及更早版本形成相违背（其中类必须是被文档记录的类（documented class））。
 
  
从类和接口继承注释有三种可能情况：
 
  
 
   
当类中的方法重写超类中的方法时
 
   
当接口中的方法覆盖超级接口中的方法时
 
   
当类中的方法实现接口中的方法时
 
  
 
  
在前两种情况下，对于方法覆盖，Javadoc工具在重写的方法的文档中生成一个子标题“Overrides”，其中包含指向它所覆盖的方法的链接，无论注释是否被继承。
 
  
在第三种情况下，Javadoc工具在重写方法的文档中生成子标题“Specified by”，并带有指向它所实现的方法的链接。无论注释是否被继承。
 
  
用于继承方法注释的算法 - 如果方法没有文档注释或者方法的文档注释中有{@inheritDoc}标签，则Javadoc工具使用以下算法搜索最具体适用的注释，该算法优先考虑接口，而不是超类：
 
  
 
   
按照它们在方法声明中的implements（或extends）后面出现的顺序查看每个直接实现（或扩展）的接口。使用此方法找到的第一个doc注释。
 
   
如果步骤1未能找到文档注释，则以与步骤1中检查的顺序相同的顺序递归地将此整个算法应用于每个直接实现（或扩展）的接口。
 
   
如果步骤2找不到文档注释，并且这是一个除Object之外的类（不是接口）：1，如果超类具有此方法的doc注释，那么就使用它。2，如果步骤1未能找到doc注释，则递归地将整个算法应用于超类。
 
  
 
  
 
 
  
References
 
  
 
  
1. How to Write Doc Comments for Javadoc
 
  
2. Javadoc 1.5 
 
  
3. Javadoc Tool Reference Page (Microsoft Windows)
 
  
4. Cay S. Horstmann,Gary Cornell,  Core Java volume I,Ninth Edition