Javadoc详解

Java

 2023/09/19

Javadoc详解

基本语法

// /**/ 行注释
/* / 块注释

标签	描述	示例
@author	标识一个类的作者	@author description
@deprecated	指名一个过期的类或成员	@deprecated description
{@docRoot}	指明当前文档根目录的路径	Directory Path
@exception	标志一个类抛出的异常	@exception exception-name explanation
{@inheritDoc}	从直接父类继承的注释	Inherits a comment from the immediate surperclass.
{@link}	插入一个到另一个主题的链接	{@link name text}
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体	Inserts an in-line link to another topic.
@param	说明一个方法的参数	@param parameter-name explanation
@return	说明返回值类型	@return explanation
@see	指定一个到另一个主题的链接	@see anchor
@serial	说明一个序列化属性	@serial description
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据	@serialData description
@serialField	说明一个ObjectStreamField组件	@serialField name type description
@since	标记当引入一个特定的变化时	@since release
@throws	和 @exception标签一样.	The @throws tag has the same meaning as the @exception tag.
{@value}	显示常量的值，该常量必须是static属性。	Displays the value of a constant, which must be a static field.
@version	指定类的版本	@version info

注意：

标签的顺序是有规范的。一般带@的标签要放在快注释的最下面。

{}的标签可以随意的插入任何地方

标签顺序

按以下顺序包含标签：

@author（仅限类和接口，需要）
@version（仅限类和接口，需要。见脚注1）
@param（仅限方法和构造函数）
@return（仅限方法）
@exception(@throws是在Javadoc 1.2中添加的同义词）
@see
@since
@serial（或@serialField或@serialData）
@deprecated（请参阅如何以及何时弃用API）

以“@”字符开头的第一行以描述结束。每个文档注释只有一个描述块；您无法在块标签后面继续描述。

自定义标签or地标

在注释内可以使用todo xxx fixme这些地标

可以从idea中的todo选项卡中快速检索

可以自定义自己的地标，也可以在todo选项卡中自定义过滤条件

当然设置中也是有的

地标也支持模板配置，比如idea自带的todo。在注释中输入tudo

规范

oracle java doc规范

一些case：

不要在首句中使用 @link

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

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

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

使用 @param、@return 和 @throws

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

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

null情况要注明

list边界条件要注明，比如not empty

@author经过迭代已经不能还原代码是谁写的了，不要用，git会帮你记住作者

javadoc规范推荐所有 Public 和 Protected 方法都应当有相应的 Javadoc。Package 和 Private 方法不强求，但是最好每个方法，都有注释

文档格式

javadoc一般生成文档是HTML格式。

所以块注释支持一般的html标签

换行<br>
分段<p>
<p><ul>
<li>the first item
<li>the second item
<li>the third item
</ul><p>

工具

模板工具

idea中也可以设置一些模板来生成注释

模板代码的写法，感兴趣的同学可以自行搜索apache velocity语法。可以生成各种不同的java代码，包括注释。这里就不展开了

自动生成html的javadoc命令

javadoc -d 文档存放目录源文件名.java

javadoc 源文件名.java

通过IDEA生成Javadoc

Tools -> Generate JavaDoc

https://jautodoc.sourceforge.net

文档注释检查工具

oracle提供了一个用于检车文档注释的工具：DocCheck。您在源代码上运行它，它会生成一份报告，描述注释的样式和标签错误，并建议更改。我们试图使其规则符合本文件中的规则。

DocCheck是一个Javadoc doclet或“插件”，因此需要安装Javadoc工具（作为Java 2标准版SDK的一部分）。

我们的lint也会检查注释，只用lint扫描就可以了。

最终演示


/**
 * <p>
 * 列表<ul>
 * <li>the first item
 * <li>the second item
 * <li>the third item
 * </ul><p>
 * 我是个换行<br>
 * <p>我是个段落<p/>
 * {@link String} 我是代码引用 <br>
 * {@code String} 我是代码高亮，单是不跳转<br>
 * <a href="https://developer.android.com/guide/components/activities/tasks-and-back-stack">我是个链接 activity stacks</a>
 * <p>
 * 以下摘抄自Activity的doc
 * <p>Topics covered here:
 * <ol>
 * <li><a href="#Fragments">Fragments</a>
 * <li><a href="#ActivityLifecycle">Activity Lifecycle</a>
 * <li><a href="#ConfigurationChanges">Configuration Changes</a>
 * <li><a href="#StartingActivities">Starting Activities and Getting Results</a>
 * <li><a href="#SavingPersistentState">Saving Persistent State</a>
 * <li><a href="#Permissions">Permissions</a>
 * <li><a href="#ProcessLifecycle">Process Lifecycle</a>
 * </ol>
 *
 * <div class="special reference">
 * <h3>Developer Guides</h3>
 * <p>The Activity class is an important part of an application's overall lifecycle,
 * and the way activities are launched and put together is a fundamental
 * part of the platform's application model. For a detailed perspective on the structure of an
 * Android application and how activities behave, please read the
 * <a href="{@docRoot}guide/topics/fundamentals.html">Application Fundamentals</a> and
 * <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a>
 * developer guides.</p>
 *
 * <p>You can also find a detailed discussion about how to create activities in the
 * <a href="{@docRoot}guide/components/activities.html">Activities</a>
 * developer guide.</p>
 * </div>
 *
 *
 * <p>Activities in the system are managed as
 * <a href="https://developer.android.com/guide/components/activities/tasks-and-back-stack">
 * activity stacks</a>. When a new activity is started, it is usually placed on the top of the
 * current stack and becomes the running activity -- the previous activity always remains
 * below it in the stack, and will not come to the foreground again until
 * the new activity exits. There can be one or multiple activity stacks visible
 * on screen.</p>
 *
 * @see Thread 我是see
 * @see Thread#checkAccess()
 * @see #run(String)
 */
public class TestJavaDoc {
    /**
     * 方法说明，和下方的参数之间要加个换行
     *
     * @param param
     * @return true xxx false xxx
     * @throws NullPointerException
     * @throws IndexOutOfBoundsException
     */
    public boolean run(String param) {
        return true;
    }
}

Kotlin

Kotlin中注释的语法跟java一样，有三种：单行注释（//）、多行注释（/…/）和文档注释（/*…/）。

kotlin文档注释就是指这种注释内容能够生成API帮助文档，称为Kdoc。Kdoc是通过一些工具从Kotlin源代码的文档注释中提取信息，并生成HTML文件，即Kdoc文档。文档注释主要对类（或接口）、属性和函数等进行注释。

kotlin工具

为了更方便的快速注释，可以在androidstudio中添加插件BugKotlinDocument或Kotlin Doc Generator。Kotlin Doc Generator相较于前者功能更多一点，其中之一是会把方法名按照英文单词拆分直接显示出来。

kotlin文档规范

kotlin文档完全集成了javadoc的标签语法。但是提倡用更加简洁的方式来编写注释。

kdoc 在样式上，摒弃了html。支持了Markdown语法，

演示

/**
 * [String]
 * [String.trimEnd]
 * See [Android](https://developer.android.google.cn/)
 *

// 测试代码
fun testA() {
if() {
}
}

 *
 * # 标题1
 * ## 标题2
 *
 * * 列表1
 *      * 子列表1
 */
class TestKotlinDoc {
    /**
     * 测试方法
     *
     * [param] 参数说明
     */
    fun test(param: String) {
    }
}

