Javadoc（最初是JavaDoc）[1]是由Sun Microsystems为Java语言（现在由甲骨文公司拥有）创建的文档生成器，用于从Java源代码生成HTML格式的API文档，HTML格式用于增加将相关文档链接在一起的便利性。[2]
Javadoc使用的“doc comments”格式[3] 是记录Java类的事实上的行业标准。一些IDE，[4]如IntelliJ IDEA、NetBeans和Eclipse，可以自动生成Javadoc HTML。许多文件编辑器帮助用户生成Javadoc源代码并使用Javadoc信息作为程序员的内部引用。
Javadoc还提供了用于创建doclet和taglet的API，允许用户分析Java应用程序的结构，这就是JDiff如何生成两个API版本之间发生变化的报告。
Javadoc不影响Java中的性能，因为在编译时会删除所有注释。编写注释和Javadoc是为了更好地理解代码，从而更好地维护代码。
历史
Javadoc是早期的Java语言文档生成器。[5]在使用文档生成器之前，习惯上由专业的技术编写者编辑文档，他们通常只编写软件的独立文档，[6]但要使这些文档与软件本身保持同步要困难得多。
自第一个版本以来，Java一直使用Javadoc，并且通常在Java开发工具包的每个新版本上都会更新。
技术架构
通过标准多行注释标记/* and */从代码中引发Javadoc注释。起始标记（称为开始 - 注释分隔符）具有额外的星号，如/**中所示。
- 第一段是对所记录方法的描述。
- 在描述之后是不同数量的描述性标签，表示：
- 方法的参数（
@param） - 方法返回的内容（
@return） - 方法可能抛出的任何异常（
@exception） - 其他不太常见的标签，如
@see（“另见”标签）
- 方法的参数（
编写文档注释的基本结构是将它们嵌入到/**.中。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;
请注意，不建议[7]在单个文档注释中定义多个变量。这是因为Javadoc读取每个变量并将它们分别放置到生成的HTML页面，其中包含为所有字段复制的相同文档注释。
/**
* 点对 (x,y) 的水平和垂直距离
*/
public int x, y; // 避免这样的做法
相反，建议分别声明和注释每个变量：
/**
* 点的水平距离。
*/
public int x;
/**
* 点的垂直距离。
*/
public int y;
一部分可用的Javadoc标签[8]列在下表中：
| 标签&参数 | 用途 | 适用于 | 引入版本 |
|---|---|---|---|
| @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
}
参见
- 文档生成器的比较
- .Net的XML文档注释
参考文献
Wikiwand in your browser!
Seamless Wikipedia browsing. On steroids.
Every time you click a link to Wikipedia, Wiktionary or Wikiquote in your browser's search results, it will show the modern Wikiwand interface.
Wikiwand extension is a five stars, simple, with minimum permission required to keep your browsing private, safe and transparent.
