小白都看得懂的Javadoc使用教程

Javadoc是什么

官方回答: Javadoc is a tool for generating API documentation in HTML format from doc comments in source code.
译：Javadoc是一款能根据源代码中的文档注释来产生HTML格式的API文档的工具。

说人话：只要你在java源码中按一定的格式写注释，就可以利用javadoc这款工具自动生成配套的API文档。

所以本篇文章的主要内容就是告诉读者们这个注释要按什么样的格式写，只要格式对了，配套的API文档就水到渠成了。

Javadoc注释分类

Javadoc注释根据写法和位置的不同，主要分为以下3类：

1. 写在类/方法上面的Javadoc注释
2. 写在字段上面的Javadoc
3. 写在包上面的Javadoc

写在类上和方法上面的Javadoc注释尽管位置不同，但是写法相同，因此将其归为一类。

以下是几点通用的注意事项：

1. 所有的Javadoc注释都以/**开头，*/结尾。
2. 每种Javadoc注释都要和其后对应的类/方法/字段/包保持同样的缩进，以下例子就是错误的。

class student {

/**
 * 没有和下面的方法保持同样的缩进，是错误的.
 */
    public int getName(int ID){
        ...
    }
}

接下来将一一介绍每类注释的写法。

写在类/方法上面的Javadoc注释

此种注释分为三段，顺序如下：

1. 概要描述 (main description)。用一句话或者一段话简要描述该类的作用，以英文句号结束，这句话会被提取并放到索引目录中。(当识别到第一个英文句号时，系统会自动认为概要描述已经结束，紧接其后的话都不会被放到概要中。要避免这种情况，可以在英文句号后加上   即可，这样系统将判定   后的下一个英文句号为概要描述结束的标志)
2. 详细描述。用一段话或者多段话详细描述该类的作用，每段话都以英文句号结束。详细描述中可以使用html标签，如<p> (定义段落，写在段前), <pre> (放在该标签内的内容可以保留“原始样子”，详见本文3.12), <a> (定义超链接), <li> (定义列表项目) 等标签。
3. 文档标记，即类似小标签一样的说明。

注意：

• 描述部分和文档标记之间必须空一行。

例子：

/**
* Graphics is the abstract base class for all graphics contexts
* which allow an application to draw onto components realized on 
* various devices or onto off-screen images.
* <p>
* A Graphics object encapsulates the state information needed
* for the various rendering operations that Java supports. This
* state information includes:
* <ul>
* <li>The current clip
* <li>The current color
* <li>The current font
* </ul>
* <p>
* Some important points to consider are that drawing a figure that
* covers a given rectangle will occupy one extra row of pixels on
* the right and bottom edges compared to filling a figure that is
* bounded by that same rectangle.
* <p>
* All coordinates which appear as arguments to the methods of this
* Graphics object are considered relative to the translation origin
* of this Graphics object prior to the invocation of the method.
* 
* @author      Sami Shaio
* @since       1.0
*/
public abstract class Graphics {
    /** 
    * Draws as much of the specified image as is currently available
    * with its northwest corner at the specified coordinate (x, y).
    * This method will return immediately in all cases.
    * <p>
    * If the current output representation is not yet complete then
    * the method will return false and the indicated 
    * {@link ImageObserver} object will be notified as the
    * conversion process progresses.
    *
    * @param img       the image to be drawn
    * @param x         the x-coordinate of the northwest corner
    *                  of the destination rectangle in pixels
    * @param y         the y-coordinate of the northwest corner
    *                  of the destination rectangle in pixels
    * @param observer  the image observer to be notified as more
    *                  of the image is converted.  May be 
    *                  <code>null</code>
    * @return          <code>true</code> if the image is completely 
    *                  loaded and was painted successfully; 
    *                  <code>false</code> otherwise.
    * @see             Image
    * @see             ImageObserver
    * @since           1.0
    */
    public abstract boolean drawImage(Image img, int x, int y, 
ImageObserver observer);

写在包上面的Javadoc

格式和写在类、方法上面的javadoc的格式一样。内容方面主要是介绍这个包是干嘛的，包的结构，在使用方面要注意什么等信息。
包注释是写在package-info.java这个文件里的，该文件在创建包时会顺带生成。

例子：

/**
 * Provides the classes necessary to create an applet and the classes an applet uses 
 * to communicate with its applet context. 
 * <p>
 * The applet framework involves two entities: 
 * the applet and the applet context. An applet is an embeddable window (see the 
 * {@link java.awt.Panel} class) with a few extra methods that the applet context 
 * can use to initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

写在字段上面的Javadoc

只有public的字段才需要注释，通常是static的。
例子：

/**
* the static field a
*/
public static int a = 1;

文档标记 (block tags)

接下来将会介绍几个常用的标签。上文也提到过，文档标记常放于包/类/方法的Javadoc注释的第三段。

@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;  

效果展示：
因为是写在字段上的javadoc，所以会出现在生成的API文档里的字段概要。

点进去后可看到详细介绍。

@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 必须放在某一行中的最开始，顶头写。
• @link 太多有时反而不利于理解注释，官方推荐在以下两种情况使用该标签（当超链接的信息补充有利于读者更进一步了解当前API或者当注释里提到的API是第一次出现时，使用 @link 标签）：
  

  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 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 // 错误使用

{@inheritDoc}

说明：用于继承父类的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} 插入子类的描述部分。

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取代了。用 @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) {
    ...
}

效果展示：

可以看到，带有 <pre> 标签的描述部分在生成的API文档中仍然保留着在注释中的原始格式。

一些习惯

• 使用第三人称而非第二人称

Gets the label. (preferred)
Get the label. (avoid)

• 方法的描述应该以动词开头

Gets the label of this button. (preferred)
This method gets the label of this button. (avoid)

• 当描述类/接口/域时，不需要再说一遍“类”，“接口”这些词。
  (Class/interface/field descriptions can omit the subject and simply state the object.)

A button label. (preferred)
This field is a button label. (avoid)

• 使用”this”而非”the”，当指向的是从当前class创建的object
  (Use “this” instead of “the” when referring to an object created from the current class.)
  例如，当class student中有一个叫getStudentID的方法，该方法的描述应为如下：

Gets the student ID for this student. (preferred)
Gets the student ID for the student. (avoid)

• 避免拉丁风格的缩写
  使用”that is”而非”i.e.”，使用”for example”而非”e.g.”等等。
• Tags的顺序
  • tags应该以如下顺序：author, version, param, return, exception, see, since, serial, deprecated.
  • 如果有好多个一组的标签（例如有好多个 @author 标签），那么这组标签要和其他标签之间空一行。
  • @author 应该按参与的顺序排列，排在第一个的就是该class的创始人。
  • @param 要按方法里参数的声明顺序排列。
  • @throws 要按exception的字母顺序排列。
  • @see 要按访问的远近排列。具体可看官网。
• 关于匿名类、内部类的文档注释
  它们的文档注释不会被javadoc提取，只有将它们的信息写在相近类的文档注释中，它们的信息才能显示在生成的文档里。

总结

Javadoc是一款为程序生成API文档的工具。只需按照规定的格式填写注释，再用IDE生成即可生成与程序对应的API文档。本文先介绍了3类Javadoc的注释格式，再对部分常用的文档标签 (block tags) 进行了详细地讲解。

参考

1. https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#inheritingcomments
2. https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#examples
3. https://www.cnblogs.com/KingIceMou/p/7169744.html
4. https://blog.51cto.com/winters1224/875466
5. https://www.cnblogs.com/boring09/p/4274893.html

 
有问题欢迎大家在评论区留言，转载请注明出处。