Javadoc

Javadoc（最初是JavaDoc）现在写作‘Javadoc’，参见 。最早写作‘JavaDoc’，参见 是由Sun Microsystems为Java语言（现在由甲骨文公司拥有）创建的文档生成器，用于从Java源代码生成HTML格式的API文档，HTML格式用于增加将相关文档链接在一起的便利性。<div>https://web.archive.org/web/20170613233020/http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/%3C/div>

Javadoc使用的“doc comments”格式 是记录Java类的事实上的行业标准。一些IDE，IntelliJ IDEA , NetBeans  and Eclipse 如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 tags in JavaSE 6 列在下表中：
标签&参数用途适用于引入版本@author John Smith描述作者。类、接口、枚举{@docRoot}表示从任何生成的页面生成的文档的根目录的相对路径。类、接口、枚举、成员、方法@version 版本提供软件版本，每个类或接口最多一个。类、接口、枚举@since 起始描述此功能首次存在的时间。类、接口、枚举、成员、方法@see 参考提供指向其他文档元素的链接。类、接口、枚举、成员、方法@param 名称 描述描述方法的一个参数。方法@return 描述描述返回值。方法@exception 类 描述@throws 类 描述描述可能从此方法抛出的异常。方法@deprecated 描述描述一个过时的方法。类、接口、枚举、成员、方法{@inheritDoc}从被覆盖的方法复制描述。覆盖方法1.4.0{@link 参考}链接到其他符号。类、接口、枚举、成员、方法{@linkplain 参考}与{@link}相同，但链接的标签以纯文本显示，而不是代码字体。类、接口、枚举、成员、方法{@value #STATIC_FIELD}返回静态成员的值。静态成员1.4.0{@code 文本}在代码字体中格式化文字文本，等同于<code> {@literal} </code>。类、接口、枚举、成员、方法1.5.0{@literal 文本}表示文本，随附的文本被解释为不包含HTML标记或嵌套的javadoc标记。类、接口、枚举、成员、方法1.5.0{@serial 文本}在Javadoc注释中用于默认的可序列化字段。成员{@serialData 文本}记录writeObject()或writeExternal()方法写入的数据。成员、方法{@serialField 文本}记录ObjectStreamField组件。成员

 示例 
下面是注释一个方法的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
}

 参见 




 参考文献 

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