小白都看得懂的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注释根据写法和位置的不同，主要分为以下3类：

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

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

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

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

(定义段落，写在段前), (放在该标签内的内容可以保留“原始样子”，详见本文3.12), (定义超链接), (定义列表项目) 等标签。 文档标记，即类似小标签一样的说明。

注意：

例子：

* A Graphics object encapsulates the state information needed * for the various rendering operations that Java supports. This * state information includes: * * The current clip * The current color * The current font * *

* 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. *

* 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. *

* 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 * null * @return true if the image is completely * loaded and was painted successfully; * false 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这个文件里的，该文件在创建包时会顺带生成。

例子：

* 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的。 例子：

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

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

例子：

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

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

说明：将一些关键字或代码解析成代码样式（类似于英文论文中对变量使用斜体）。 注意：以下必须使用该标签。

例子：

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

例子：

说明：说明方法的参数。 注意：

例子：

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

例子：

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

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

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

例子：

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

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.

例子：

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

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

* The speed of animal will be returned. * * @return the speed of animal */ public int run(); }

将 {@inheritDoc} 插入子类的描述部分。

* 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} 插入子类的文档标签中。

* 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文档注释会被自动拷贝到子类对应缺失的部分。

说明：告诉用户该API已过时，并且已被哪些新的API取代了。用 @see 或 @link 指向新的API。该旧的API之所以不删掉，通常是为了兼容性考虑。 例子：

效果展示：

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

注意：

例子：

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

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

效果展示：

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

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

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