Appendix-Javadoc
附录: 文档注释
编写代码文档的最大问题可能是维护该文档。如果文档和代码是分开的,每次更改代码时都要很繁琐地再去更改文档。解决方案似乎很简单:将代码链接到文档。最简单的方法是将所有内容放在同一个文件中。然而,要完成这个任务,需要一个特殊的注释语法来标记文档,以及一个工具将这些注释提取为有用的形式,这就是
提取注释的工具称为
此外,你可以编写自己的
以下是对
句法规则
所有/**
开头*/
*
将被忽略@
开头,但被花括号包围。
有三种类型的注释文档,它们对应于注释前面的元素
// javadoc/Documentation1.java
/** 一个类注释 */
public class Documentation1 {
/** 一个属性注释 */
public int i;
/** 一个方法注释 */
public void f() {}
}
要通过
javadoc Documentation1.java
这将产生一组
内嵌HTML
// javadoc/Documentation2.java
/** <pre>
* System.out.println(new Date());
* </pre>
*/
public class Documentation2 {}
你也可以像在其他任何
// javadoc/Documentation3.java
/** You can <em>even</em> insert a list:
* <ol>
* <li> Item one
* <li> Item two
* <li> Item three
* </ol>
*/
public class Documentation3 {}
请注意,在文档注释中,<h1>
和<hr>
之类的标题用作嵌入式
所有类型的注释文档(类,字段和方法)都可以支持嵌入式
示例标签
以下是一些可用于代码文档的
@see
这个标签可以将其它的类链接到本文档中。@see
标签产生链接到其它类的的
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
每个都向生成的文档中添加超链接的“另请参阅”条目。
{@link package.class#member label}
和
{@docRoot}
生成文档根目录的相对路径。对于显式超链接到文档树中的页面很有用。
{@inheritDoc}
将文档从此类的最近基类继承到当前文档注释中。
@version
其形式为:
@version version-information
其中
@author
其形式为:
@author author-information
你可以对作者列表使用多个作者标签,但是必须连续放置它们。所有作者信息都集中在生成的
@since
此标记指示此代码的版本开始使用特定功能。例如,它出现在
@param
这将生成有关方法参数的文档:
@param parameter-name description
其中 parameter-name
是方法参数列表中的标识符, description
是可以在后续行中继续的文本。当遇到新的文档标签时,这个说明被视为结束。@param
标签可以使用任意次,大概每个参数使用一次。
@return
这记录了返回值:
@return description
其中
@throws
一个方法可以产生许多不同类型的异常,所有这些异常都需要描述。异常标记的形式为:
@throws fully-qualified-class-name description
@deprecated
表示已被改进的功能取代的功能。@deprecated
的方法会使编译器发出警告。在@deprecated
@Deprecated
注解 取代(在注解一章中进行了描述
文档示例
// javadoc/HelloDateDoc.java
import java.util.*;
/** The first On Java 8 example program.
* Displays a String and today's date.
* @author Bruce Eckel
* @author www.MindviewInc.com
* @version 5.0
*/
public class HelloDateDoc {
/** Entry point to class & application.
* @param args array of String arguments
* @throws exceptions No exceptions thrown
*/
public static void main(String[] args) {
System.out.println("Hello, it's: ");
System.out.println(new Date());
}
}
/* Output:
Hello, it's:
Tue May 09 06:07:27 MDT 2017
*/
你可以在