Javadoc

For Example

类级别的Javadoc

/**
* Hero is the main entity we'll be using to . . .
* 
* Please see the {@link com.baeldung.javadoc.Person} class for true identity
* @author Captain America
* 
*/
public class SuperHero extends Person {
    // fields and methods
}

字段级别的javadoc

/**
 * The public name of a hero that is common knowledge
 */
private String heroName;

方法级别的javadoc

/**
 * <p>This is a simple description of the method. . .
 * <a href="http://www.supermanisthegreatest.com">Superman!</a>
 * </p>
 * @param incomingDamage the amount of incoming damage
 * @return the amount of health hero has after attack
 * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
 * @since 1.0
 */
public int successfullyAttacked(int incomingDamage) {
    // do things
    return 0;
}

介绍

Javadoc is a tool for generating API documentation in HTML format from doc comments in source code.

译：Javadoc是一款能根据源代码中的文档注释来产生HTML格式的API文档的工具。

常用注解

@author

说明：用于指明作者。可以附加邮箱或者超链接。

注意：有多少个作者就用多少个该标签。有时候留的是组织名或者邮箱。

不知道作者是谁时，就写@author unascribed，意为无名氏

// 纯文本作者
@author Steve Johnson

// 纯文本组织
@author Apache Software Foundation

// 纯文本邮箱
@author shane_curcuru@us.ibm.com

// 纯文本作者 + 邮箱
@author Igor Hersht, igorh@ca.ibm.com

// 纯文本作者 + 超链接邮箱
@author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>

// 纯文本组织 + 超链接组织地址
@author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>

@since

说明：用于指明最早出现在哪个版本，可填版本号或日期，有时也可表明可运行的JDK版本。

例子：

// 版本号
@since 1.4

// 日期
@since 15 April 2001

// 可运行的JDK版本
@since JDK1.5

@version

说明：用于指明当前版本号。

例子：

@version 1.8.3.4

@code

说明：将一些关键字或代码解析成代码样式（类似于英文论文中对变量使用斜体）。

注意：以下必须使用该标签。

Java keywords.
package names.
class names.
method names.
interface names.
field names.
argument names.
code examples.

例子：

// 关键字
{@code true}
{@code null}

// 变量名
{@code CharSequence}

// 代码
{@code int var = 1;}

@return

说明：用于说明return的内容。

注意：方法有返回值时，必须包含该标签。

例子：

@return     {@code true} if the image is completely 
            loaded and was painted successfully; 
            {@code false} otherwise.

@return     {@code true} if the {@code CharSequence} is not 
            {@code null}.

@param

说明：说明方法的参数。

注意：先接参数名，再接参数描述。有几个参数就用几个该标签。

例子：

@param  img     the image to be drawn
@param  x       the x-coordinate of the northwest corner
                of the destination rectangle in pixels

@value

说明：只能用于对常量进行注释，该标签常用于写在字段上的Javadoc注释。

注意：格式：常量说明. {@value #常量名}当常量名打错时，系统会提示值不引用常量以及找不到引用两个错误。

例子：

/**
* Default delimiter. {@value #DEFAULT_LIST_SEPARATOR}
*/
public final static String DEFAULT_LIST_SEPARATOR = ",";

/**
* Default start value. {@value #START_VALUE}
*/
public final static int START_VALUE = 20000;

@throws @exception

说明：描述何时会抛出异常。

注意： @throws 和 @exception是一模一样的。

例子：

@throws IOException             If an input or output exception occurred     

@throws IllegalArgumentException When the given source contains invalid encoded sequences

@link @linkplain @see

说明：用于创建一个超链接到相关代码。

@link 和 @linkplain的区别

@link 直接将将超链接中的地址当作显示的文本，其格式为 {@link 地址}；

@linkplain 可以自行设定显示的文本，其格式为 {@link 地址显示文本}，三个字段用空格隔开。其中地址的格式为包名.类名#方法名(参数类型)。当当前类中已经导入了包名可以省略，可以只是一个类名或一个方法名。

@link 和 @see的区别

@link 可以放在某一行中的任意位置；

@see 必须放在某一行中的最开始，顶头写。

The user might actually want to click on it for more information. Only for the first occurance of each API name in the doc comment.

@link 太多有时反而不利于理解注释，官方推荐在以下两种情况使用该标签（当超链接的信息补充有利于读者更进一步了解当前API或者当注释里提到的API是第一次出现时，使用 @link 标签）：

例子：

// 完整格式
{@link java.lang.String#charAt(int)}

// 省略包名
{@link String}

// 省略包名和类名，表示指向当前的某个方法
{@link #length()}

// @link
此实现继承了{@link com.service.BaseManagerImpl}，以复用其中的dao接口。
// 显示结果：此实现继承了com.service.BaseManagerImpl，以复用其中的dao接口。

// @linkplain
使用方法与{@linkplain com.common.web.SimpleDBAction SimpleDBAction}基本一致
// 显示结果：使用方法与SimpleDBAction基本一致  

// @see
@see DoubleStream // 正确使用
related usage can be checked on @see DoubleStream // 错误使用

说明：用于继承父类的javadoc注释，父类的文档注释会被拷贝到子类。

注意：

该标签可以放于描述部分。对应地，父类注释中的描述部分会被拷贝到子类的描述部分。
该标签还可以放于 @return, @param, @throws 文档标签中。对应地，父类注释中的文档标签会被拷贝到子类的文档标签。

接下来我们分别看看该标签被插进描述部分以及文档标签中的效果。

public interface animal {
    /**
     * An animal is running.
     * <p>
     * The speed of animal will be returned.
     * 
     * @return the speed of animal
     */
    public int run();
}

将 {@inheritDoc} 插入子类的描述部分。在父类的描述上增加属于The speed of tiger will be returned.

public class tiger implements animal {

    /**
     * {@inheritDoc}
     * <p>
     * The speed of tiger will be returned.
     * 
     * @return the speed of tiger 
     */
    @Override
    public int run() {
        // TODO Auto-generated method stub
        System.out.println("The tiger is running.");
	return 150;
    }

}

结果展示：

将 {@inheritDoc} 插入子类的文档标签中。

public class tiger implements animal {

    /**
     * A tiger is running.
     * <p>
     * The speed of tiger will be returned.
     * 
     * @return {@inheritDoc}
     */
    @Override
    public int run() {
        // TODO Auto-generated method stub
        System.out.println("The tiger is running.");
	return 150;
    }
}

结果展示：

当描述部分或者文档标记部分缺失时，不需要 {@inheritDoc} 标签，父类的Javadoc文档注释会被自动拷贝到子类对应缺失的部分。

@deprecated API过期

说明：告诉用户该API已过时，并且已被哪些新的API取代了。用 @see 或 @link 指向新的API。

该旧的API之所以不删掉，通常是为了兼容性考虑。

例子：

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

效果展示：

`<pre>`

说明：放在该标签内的内容可以保留“原始样子”。

严格来说，这是html标签，而不属于文档标签，但由于其经常用在描述部分，所以也详细介绍一下。

例子：

/**
 * Returns n factorial.
 * <p>
 * Example of calling the method:
 * <pre>
 * public void main(String[] args) {
 * 	System.out.println(factorial(5));
 * }
 * </pre>
 */
public static int factorial(int n) {
    ...
}

/**
 * Returns n factorial.
 * <p>
 * Example of calling the method:
 * public void main(String[] args) {
 * 	System.out.println(factorial(5));
 * }
 */
public static int factorial1(int n) {
    ...
}

效果展示：

自定义注解

除了使用预定义的块标记格式化文档外，我们还可以创建自定义块标记。

Javadoc

在 Javadoc 命令行中新增注解< locations>,格式如下

< tag-name > : < locations-allowed > : < header >

user@baeldung:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

为了使用这个标签，我们可以把它添加到 Javadoc 注释的 block 部分:

/**
 * This is an example...
 * @location New York
 * @returns blah blah
 */

看不懂,可以先看下方maven javadoc的<tags>格式就应该懂了

maven Javadoc

Mavenjavadoc 插件非常灵活，允许在 pom.xml 中定义自定义标记。在插件的 < tags > 部分添加以下内容:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
                <tag>
                    <name>location</name>
                    <placement>a</placement>
                    <head>Notable Places:</head>
                </tag> 
            </tags>
        </plugin>
    </plugins>
</build>

如何生成Javadoc

JDK 附带的命令行工具和 Maven 插件

jdk命令

假设所有的类都在项目目录下的 src 文件夹中:

user@baeldung:~$ javadoc -d doc src\*

这将在一个名为 doc 的目录中生成由 -d 标志指定的文档。

Maven插件

使用 Maven Javadoc 插件,在pom.xml中追加

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
            ...
            </tags>
        </plugin>
    </plugins>
</build>

在项目的基本目录中，我们运行命令将 Javadocs 生成到目标站点的目录中:

user@baeldung:~$ mvn javadoc:javadoc

实践事项

让 Javadoc 像代码一样可读

当你听到 “Javadoc” 这个词的时候，你首先想到的可能是 Javadoc 生成的 HTML 网页，然而实际情况绝非如此。多数情况下，其他人都是在看源代码的时候用到这些 Javadoc，比如你看同事的代码、或是研究第三方库的代码。时刻记住：让 Javadoc 像 Java 代码一样保持可读性。

Public 和 Protected

所有 Public 和 Protected 方法都应当有相应的 Javadoc。Package 和 Private 方法不强求，但是如果有帮助的话加上也很好。

如果子类覆盖了父类中的某个方法，一般来说不需要 Javadoc，除非这个覆盖的实现和原有的差别很大，这时候需要用 Javadoc 说明差异的那部分。@Override 注解不仅标记了方法覆盖，另一方面也是暗示读者要参考原来方法上的文档一起看。

使用标准的 Javadoc 风格注释

Javadoc 以 /** 开头、以 */ 结尾，并且每行要以星号开头：

/**
 * Standard comment.
 */
public ...

/** Compressed comment. */
public ...

注意别用 **/ 作结尾。

用简单的 HTML tags 就行了，不需要 XHTML

Javadoc 用 HTML tags 来识别段落、列表等等。很多开发者可能觉得 XHTML（HTML 的一种“严格版本”）会更好，其实不然。XHTML 常常会多出一些 tag，这会导致代码变得更复杂了，可读性更差。

此外，Javadoc 的 parser 其实会帮你把没闭合的 tags 自动闭合的，别担心。

用单个 <p> 来分割段落

Javadoc 经常会需要分成好几段。所以问题来了：怎样优雅地加上段落标记？答案是，在两段之间写上一行 <p> 就可以了，不用加 </p> 闭合它。

/**
 * First paragraph.
 * <p>
 * Second paragraph.
 * May be on multiple lines.
 * <p>
 * Third paragraph.
 */
public ...

用单个 <li> 来标记列表项

列表在 Javadoc 中也很常用，比如用来表示一组选项、一些问题等等。推荐的做法是用一个 <li> 作为每项的开头，同样不需要闭合。此外，别忘了加段落 tag：

/**
 * First paragraph.
 * <p><ul>
 * <li>the first item
 * <li>the second item
 * <li>the third item
 * </ul><p>
 * Second paragraph.
 */
public ...

首句很重要

Javadoc 的首句（用英文句号结束）也被作为这个 Javadoc 的摘要，在折叠的时候只会显示这一句。因此首句必须是个总结性的描述，它最好简洁有力，不能太长。

用 “this” 指代类的对象

当你想描述这个类的一个实例（对象）的时候，用 “this” 来指代它，比如 “Returns a copy of this foo with the bar value updated”

别写太长的句子

尽量让一句话能容纳在一行中，一般来说一行有 80 到 120 个字符。

新的句子就另起一行，这会让代码可读性更好，也会让以后改写 Javadoc 容易很多。

/**
 * This is the first paragraph, on one line.
 * <p>
 * This is the first sentence of the second paragraph, on one line.
 * This is the second sentence of the second paragraph, on one line.
 * This is the third sentence of the second paragraph which is a bit longer so has been
 * split onto a second line, as that makes sense.
 * This is the fourth sentence, which starts a new line, even though there is space above.
 */
public ...

正确使用 @link 和 @code

很多地方的描述需要涉及到其他类或方法，这时最好用 @link 和 @code。

@link 会最终变成一个超链接，它有以下几种形式：

/**
 * First paragraph.
 * <p>
 * Link to a class named 'Foo': {@link Foo}.
 * Link to a method 'bar' on a class named 'Foo': {@link Foo#bar}.
 * Link to a method 'baz' on this class: {@link #baz}.
 * Link specifying text of the hyperlink after a space: {@link Foo the Foo class}.
 * Link to a method handling method overload {@link Foo#bar(String,int)}.
 */
public ...

@code 用来标记一小段等宽字体，也可以用来标记某个类或方法，但不会生成超链接。

建议在第一次提到某个类或方法的时候用 @link，此后直接用 @code 即可。

不要在首句中使用 @link

之前提到，Javadoc 的首句也被用作概要，首句中的超链接会让读者感到混乱。如果一定要在第一句话中引用其它类或方法，始终用 @code 而不是 @link，第二句开始再用 @link。

null、true、false 不必用 @code 标记

null、true、false 这些词在 Javadoc 中太常用了，如果每次都加上 @code，无论是对读者还是作者都是个负担。

使用 @param、@return 和 @throws

几乎所有方法都会输入几个参数、输出一个结果，@param 和 @return 就是用来描述这些输入输出参数的，@throws 用于描述方法抛出的异常。

如果有多个输入参数，@param 的顺序也要和参数一致。@return 应当始终放在 @param 之后，然后才是 @throws。

为范型参数加上 @param

如果一个类或方法有范型参数（例如 <T>），这些参数也应当被文档化，推荐的做法是给 <T> 也加上一个 @param 说明。

在 @param 之前空一行

始终在 Javadoc 的内容和 @param、@return 之间留个空行，这让代码的可读性更佳。

用短语来描述 @param 和 @return

@param 和 @return 后面跟的的描述是个短语，而非完整的句子，因此它得用小写字母开头（经常是 the），结尾也不需要用句号。

用 if-句来描述 @throws

@throws 通常跟着一个 “if” 句子来描述抛异常的情形，比如 “@throws IllegalArgumentException if the file could not be found”。

@param 的参数名之后空两格

在源代码中阅读 Javadoc 的时候，如果参数名后面只有一个空格，读起来会有点困难，两个空格就好很多。另外，避免把参数按列对齐，否则参数改名、增减参数的时候会很麻烦。

**
 * Javadoc text.
 * 
 * @param foo  the foo parameter
 * @param bar  the bar parameter
 * @return the baz content
 */
public String process(String foo, String bar) {...}

写明各参数和返回值的 null 行为

一个方法是否接受 null、会不会返回 null 对于其他开发者是十分重要的信息。除非是原始类型，@param 和 @return 都应该注明它是否接受或返回 null。以下标准若适用请务必遵循：

“not null” 表明不接受 null，若输入 null 可能导致异常，例如 NullPointerException
“may be null” 表明可以传入 null 参数
“null treated as xxx” 表明 null 值等价于某个值
“null returns xxx” 表明如果输入 null 则一定会返回某个值

定义清楚这些之后，不要再为 NullPointerException 写 @throws。

/**
 * Javadoc text.
 * 
 * @param foo  the foo parameter, not null
 * @param bar  the bar parameter, null returns null
 * @return the baz content, null if not processed
 */
public String process(String foo, String bar) {...}

有人可能想在某个地方（像是类或包的 Javadoc）集中定义 null 相关行为，但我们不建议你这么做，因为这对别人并没有帮助。方法上的 Javadoc 很容易就能看到，而类或包层级的 Javadoc 要去翻一遍才能找到。

其他简单的约束条件也建议写到 Javadoc 里，比如 “not empty, not null”。原始类型也可以加上边界约束，比如 “from 1 to 5” 或 “not negative”

给 Specification 加上 implementation notes

如果某个接口允许第三方来实现，而你为这个接口写了个正式的规格说明（specification），这时候考虑加个 “implementation notes” 章节。这通常出现在类的 Javadoc 上，用于描述一些不太好写在特定方法上的东西，或者一些其他人不感兴趣的东西。参考这个例子。

不要用 @author

@author 用来标记类的作者，这个功能已经过时了，不要用。版本控制系统（例如 git）会记住作者的。

学习链接

Spring 框架源代码
ANT-源代码svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/DefaultLogger.java?view=co
[Apache-SVN] Index of /ant/core/trunk/src/main/org/apache/tools/ant
Javadoc FAQ

参考链接

posted @ 2022-01-09 16:42 故乡的胡辣汤开张了吗阅读(67) 评论(0) 编辑收藏举报

刷新页面返回顶部

故乡的胡辣汤开张了吗

Javadoc

Javadoc

For Example

类级别的Javadoc

字段级别的javadoc

方法级别的javadoc

介绍

常用注解

@author

@since

@version

@code

@return

@param

@value

@throws @exception

@link @linkplain @see

@link 和 @linkplain的区别

@link 和 @see的区别

@deprecated API过期

<pre>

自定义注解

Javadoc

maven Javadoc

如何生成Javadoc

jdk命令

Maven插件

实践事项

学习链接

参考链接

公告

`<pre>`