Javadoc

Javadoc（最初是JavaDoc）是由Sun Microsystems为Java语言（现在由甲骨文公司拥有）创建的文档生成器，用于从Java源代码生成HTML格式的API文档，HTML格式用于增加将相关文档链接在一起的便利性。

Javadoc使用的“doc comments”格式 是记录Java类的事实上的行业标准。一些IDE，如IntelliJ IDEA、NetBeans和Eclipse，可以自动生成Javadoc HTML。许多文件编辑器帮助用户生成Javadoc源代码并使用Javadoc信息作为程序员的内部引用。

Javadoc还提供了用于创建doclet和taglet的API，允许用户分析Java应用程序的结构，这就是JDiff如何生成两个API版本之间发生变化的报告。

Javadoc不影响Java中的性能，因为在编译时会删除所有注释。编写注释和Javadoc是为了更好地理解代码，从而更好地维护代码。

历史 
Javadoc是早期的Java语言文档生成器。在使用文档生成器之前，习惯上由专业的技术编写者编辑文档，他们通常只编写软件的独立文档，但要使这些文档与软件本身保持同步要困难得多。

自第一个版本以来，Java一直使用Javadoc，并且通常在Java开发工具包的每个新版本上都会更新。

技术架构

Javadoc注释结构 
通过标准多行注释标记/* and */从代码中引发Javadoc注释。起始标记（称为开始 - 注释分隔符）具有额外的星号，如/**中所示。

 第一段是对所记录方法的描述。
 在描述之后是不同数量的描述性标签，表示：
 方法的参数（@param）
 方法返回的内容（@return）
 方法可能抛出的任何异常（@exception）
 其他不太常见的标签，如 @see （“另见”标签）

Javadoc概览 
编写文档注释的基本结构是将它们嵌入到/**.中。Javadoc写在项目旁边，没有任何分隔换行符。请注意，任何import语句必须在类声明之前。类声明通常包括：// import statements

/**
 * @author     姓名  <address @ example.com>
 * @version    1.6   （程序的当前版本号）
 * @since       1.2    （加入该类时程序的版本号）
 */
public class Test {
    // class body
}对于方法，有如（1）所示的简洁的一行描述来解释项目的作用；接下来是（2）所示的更长的描述，该描述可以跨越多个段落并且是可有可无的；最后，第（3）部分列出接受的输入参数和方法的返回值。所有的Javadoc都被视为HTML，因此多个段落部分由"<p>"段落符号分隔。/**
 * 简短的单行描述。                                                  （1）
 * <p>
 * 更长一些的描述可以写在这里。                              （2）
 * </p>
 * 在HTML段落分隔的连续段落中还可以有更多注释。
 *
 * @param  variable 描述文本。                               （3）
 * @return  描述文本。
 */
public int methodName (...) {
    // method body with a return statement
}与方法类似的注释也可以用于变量的注释，但省略了第（3）部分，这里只包含了对变量的简短描述：/**
 * 对变量的描述。
 */
private int debug = 0;请注意，不建议在单个文档注释中定义多个变量。这是因为Javadoc读取每个变量并将它们分别放置到生成的HTML页面，其中包含为所有字段复制的相同文档注释。/**
 * 点对 (x,y) 的水平和垂直距离
 */
public int x, y;      // 避免这样的做法相反，建议分别声明和注释每个变量：/**
 * 点的水平距离。
 */
public int x;

/**
 * 点的垂直距离。
 */
public int y;

Javadoc标签表 
一部分可用的Javadoc标签列在下表中：

示例 
下面是注释一个方法的Javadoc示例。/**
 * 验证一步象棋的移动是否可行。
 *
 * <p>使用 {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} 方法来移动棋子。
 *
 * @param theFromFile 被移动棋子的来源行
 * @param theFromRank 被移动棋子的来源列
 * @param theToFile  被移动棋子的目标行
 * @param theToRank  被移动棋子的目标列
 * @return            如果移动是可行的则返回true，否则返回false
 * @since             1.0
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
    // ...body
}

/**
 * 移动一个棋子。
 *
 * @see java.math.RoundingMode
 */
void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)  {
    // ...body
}

参见

参考文献 

Java开发工具
自由文档生成器
有未审阅翻译的页面