轩辕李的博客
轩辕李
2023-07-23
目录

写好Java Doc

# 一、Java Doc概述

# 1. 什么是Java Doc

Java Doc是基于注释的文档生成工具。

在Java代码中，通过特定的注释格式，可以标注类、方法、字段等的用途、参数、返回值等相关信息。

Java Doc工具会解析这些注释，并生成HTML格式的文档，以供开发者阅读和使用。

# 2. Java Doc的作用和重要性

Java Doc的作用非常重要，它可以帮助开发者更好地理解代码、使用代码和维护代码。

具体来说，Java Doc的作用包括：

  • 提供代码的详细说明：通过Java Doc注释，可以清晰地描述类、方法、字段的功能、用途和使用方法，使其他开发者能够更好地理解和使用代码。
  • 自动生成API文档：Java Doc工具可以根据注释生成HTML格式的API文档，提供给其他开发者使用。这样，其他开发者就可以快速了解代码的接口和使用规范。
  • 代码可读性增强：良好的Java Doc注释可以增加代码的可读性，使代码更易于理解和维护。注释可以提供额外的上下文信息，帮助其他开发者快速理解代码的意图和逻辑。
  • 代码文档化和规范化：通过编写Java Doc注释，可以迫使开发者对代码进行更加规范和清晰的书写，提高代码的质量和可维护性。

# 二、编写Java Doc的基本规范

在编写Java Doc时，我们需要遵循一些基本的规范，包括注释格式、注释标签和文档结构等。

这些规范可以帮助我们编写清晰、易读和易于维护的文档。

# 1. 注释格式

Java Doc注释使用/**开头，以*/结尾，位于需要注释的代码上方。注释可以跨越多行，也可以位于一行内。以下是一个示例：

/**
 * 这是一个示例的Java Doc注释
 */
public class MyClass {
    // ...
}

# 2. 注释标签

Java Doc注释使用特定的标签来标记不同的注释内容。常用的注释标签包括：

  • @param：用于描述方法的参数，指定参数的名称和说明。
  • @return：用于描述方法的返回值，指定返回值的类型和说明。
  • @throws：用于描述方法可能抛出的异常，指定异常的类型和说明。
  • @see：用于引用其他相关的文档或类。
  • @deprecated：用于标记已过时的方法或类。
  • @author：用于指定作者姓名。
  • @version：用于指定版本信息。
  • @since：用于指明最早出现在哪个版本，可填版本号或日期，有时也可表明可运行的JDK版本。

以下是一个示例：

/**
 * 这是一个示例的Java Doc注释
 * 
 * @param name 用户名
 * @param age 用户年龄
 * @return 用户信息
 * @throws IllegalArgumentException 如果用户名为空或年龄小于0
 * @see OtherClass
 * @deprecated 请使用新的方法代替
 * @author John
 * @version 1.0
 */
public String getUserInfo(String name, int age) throws IllegalArgumentException {
    // ...
}

在注释标签中，你可以使用HTML标签来做一些格式处理。比如：

/**
 * 请参考 <a href="https://example.com">此链接</a> 获取更多信息。
 */
public void referenceLink() {
    // 方法实现
}

/**
 * 这是一个 <b>重要</b> 的方法。
 */
public void importantMethod() {
    // 方法实现
}

在Java 9之后，JavaDoc开始支持HTML5标签，比如：

/**
 * <section>
 * <h2>节标题</h2>
 * <p>这是节的内容。</p>
 * </section>
 */
public void sectionExample() {
    // 方法实现
}

此外，除了上面的标签，还有一些其他的标签，用于标记一些特殊的内容，包括：

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

# @value

只能用于对常量进行注释。

/**
* Default delimiter. {@value Constant#DEFAULT_LIST_SEPARATOR}
*/
public String getListSeparator() {
    return listSeparator;
}

# @throws和@exception

@throws和@exception标签用于标记方法可能抛出的异常，指定异常的类型和说明。两者的作用相同，只是名称不同。

/**
 * 这是一个示例的Java Doc注释
 * 
 * @throws IllegalArgumentException 如果用户名为空或年龄小于0
 */
public String getUserInfo(String name, int age) throws IllegalArgumentException {
    // ...
}

# @link与@linkplain

@link和@linkplain标签用于引用其他相关的文档或类。

@link和@linkplain的区别在于：@link直接将将超链接中的地址当作显示的文本，其格式为{@link 地址}；而@linkplain可以自行设定显示的文本，其格式为{@link 地址 显示文本}，三个字段用空格隔开。

@link和@see的格式相同。以上面的内容为例，其中地址的格式为包名.类名#方法名(参数类型)。当前类中已经导入了包名可以省略，可以只是一个类名或一个方法名。

@link和@see的区别在于：@link可以放在某一行中的任意位置；而@see必须放在某一行中的最开始，顶头写。

// 完整格式
{@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

@inheritDoc标签用于继承父类的注释，可以用于类、方法和字段。

/**
 * {@inheritDoc}
 */
public class MyClass extends BaseClass {
    // ...
}

# <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) {
    ...
}

# 三、注释的内容和示例

在Java Doc中，不同的注释类型有不同的内容要求。本章将介绍模块和包注释、类和接口注释、方法注释以及字段注释的内容和示例。

# 1. 模块和包注释的内容和示例

模块和包注释通常用于描述整个代码模块或包的功能、用途和设计思路。其内容通常包括以下几个方面：

  • 模块或包的名称和简要描述
  • 模块或包的设计目标和用途
  • 模块或包的依赖关系和关联的其他模块或包
  • 模块或包的作者和版本信息

以下是一个示例：

/**
 * 这个模块提供了一些用于处理字符串的工具方法。
 * 
 * <h3>主要功能：</h3>
 * <ul>
 *     <li>字符串的拼接和分割</li>
 *     <li>字符串的格式化和解析</li>
 * </ul>
 * 
 * @author：John
 * @version：1.0
 */
module stringutils {
    // ...
}

# 2. 类和接口注释的内容和示例

类和接口注释用于描述类或接口的功能、用途和设计思路。其内容通常包括以下几个方面：

  • 类或接口的名称和简要描述
  • 类或接口的设计目标和用途
  • 类或接口的构造方法和方法的功能和用途
  • 类或接口的作者和版本信息

以下是一个示例：

/**
 * 这个类表示一个图形，可以计算图形的面积和周长。
 * <p>主要功能：</p>
 * <ul>
 *     <li>计算面积和周长</li>
 *     <li>打印图形的详细信息</li>
 * </ul>
 * 
 * @author：John
 * @version：1.0
 */
public class Shape {
    // ...
}

# 3. 方法注释的内容和示例

方法注释用于描述方法的功能、参数、返回值和异常等信息。其内容通常包括以下几个方面：

  • 方法的功能和用途
  • 方法的参数及其说明
  • 方法的返回值及其说明
  • 方法可能抛出的异常及其说明
  • 方法的作者和版本信息

以下是一个示例：

/**
 * 执行某个操作，并返回结果。
 * 
 * @param a 第一个操作数
 * @param b 第二个操作数
 * @return 执行结果
 * @throws IllegalArgumentException 如果操作数无效
 * @throws ArithmeticException 如果执行操作时发生算术错误
 * @since 1.0
 */
public int executeOperation(int a, int b) throws IllegalArgumentException, ArithmeticException {
    // ...
}

# 4. 字段注释的内容和示例

字段注释用于描述类的字段的用途和意义。

以下是一个示例：

/**
 * 用户的姓名
 */
private String name;

# 四、常见的Java Doc错误和建议

在编写Java Doc时，可能会出现一些常见的错误。本章将介绍一些常见的Java Doc错误，并提供一些建议来避免这些错误。

# 1. 缺少注释

缺少注释是一个常见的错误。没有或者缺少注释会导致其他开发者难以理解代码的意图和功能。为了避免这个错误，建议在编写代码时，及时添加注释，并确保注释清晰、准确地描述代码的功能和用途。

# 2. 注释不准确或过于冗长

另一个常见的错误是注释不准确或过于冗长。注释应该简洁明了地描述代码的功能和用途，同时避免过多的冗长描述。准确的注释可以帮助其他开发者更好地理解代码，而冗长的注释可能会让阅读代码的过程变得困难。因此，建议在编写注释时，注意准确描述代码的功能，并尽量保持简洁。

# 3. 错误的注释标签使用

使用错误的注释标签也是一个常见的错误。不正确的注释标签可能导致生成的文档不符合预期，或者无法正确解析注释的内容。为了避免这个错误，建议在编写注释时，使用正确的注释标签，并确保每个标签的使用符合Java Doc的规范和要求。

以下是一些常见的注释标签的使用示例：

  • 使用@param标签来描述方法的参数，例如：@param name 用户名
  • 使用@return标签来描述方法的返回值，例如：@return 用户信息
  • 使用@throws标签来描述方法可能抛出的异常，例如：@throws IllegalArgumentException 如果用户名为空或年龄小于0

通过正确使用注释标签，可以提供准确的代码说明和参考，帮助其他开发者更好地理解和使用代码。

总的来说，避免常见的Java Doc错误需要及时添加注释、确保注释准确简洁，并正确使用注释标签。这样可以提高代码的可读性和可维护性，使代码更易于理解和使用。

# 五、工具和插件推荐

在编写Java Doc时，有一些工具和插件可以帮助我们更好地生成和维护文档。本章将介绍一些常用的工具和插件，并提供一些推荐。

# 1. JavaDoc命令行工具

JavaDoc命令行工具是Java官方提供的一种生成Java Doc文档的工具。它可以通过命令行的方式运行，生成HTML格式的文档。使用JavaDoc命令行工具可以方便地集成到自动化构建工具中。

  1. 生成类的Java Doc文档
javadoc -d docs/ MyClass1.java MyClass2.java
  1. 生成项目的Java Doc文档
javadoc -d docs/ -sourcepath src/ -subpackages com.example
  1. 生成html5格式的Java Doc文档 从Java 9开始，JavaDoc支持HTML 5格式了。我们可以通过--html5选项来生成HTML 5格式的文档。
javadoc -d docs/ -sourcepath src/ -subpackages com.example -html5

# 2. IDE的Java Doc工具

大多数集成开发环境（IDE）都提供了Java Doc工具，可以帮助我们快速生成和维护文档。IDE的Java Doc工具通常提供了自动完成和模板功能，可以加速编写注释的过程。同时，IDE还可以集成Java Doc的预览功能，方便我们查看和阅读生成的文档。

IDE还提供了扩展性的插件，帮助我们自动生成Java Doc文档。例如，IDEA提供了Easy Javadoc (opens new window)插件，能帮助开发者快速生成类、方法、属性等中文javadoc/kdoc文档。

# 3. 第三方插件

除了IDE自带的工具外，还有一些第三方插件可以帮助我们更好地生成和维护Java Doc文档。这些插件通常提供了更丰富的功能和定制选项，使我们能够更灵活地生成文档。

以下是一些常用的第三方插件：

选择合适的工具和插件可以提高我们生成和维护Java Doc文档的效率和质量。根据个人的需求和偏好，选择适合自己的工具和插件，并合理使用它们。

# 六、Java Doc的最佳实践

编写Java Doc注释时，遵循一些最佳实践可以提高代码的可读性和可维护性。本章将介绍一些Java Doc的最佳实践。

# 1. 保持注释的更新和一致性

在编写Java Doc注释时，需要保持注释和代码的一致性，并及时更新注释。当代码发生变更时，注释也应进行相应的更新，保持注释和代码之间的一致性。这样可以避免注释过时或与代码不一致的情况发生，提高代码的可维护性。

# 2. 编写清晰和易读的注释

编写清晰和易读的注释是非常重要的。注释应该使用清晰的语言和恰当的术语，描述代码的功能和用途。注释应该避免使用模糊和含糊不清的描述，而应该尽量具体和明确地描述代码的意图。此外，注释应该注意语法和拼写错误，以确保注释的准确性和可读性。

# 3. 打破注释的模板化

虽然使用注释模板可以提高注释的一致性和规范性，但过于模板化的注释可能会导致注释的可读性下降。因此，建议在编写注释时，不要过于依赖模板，而是根据具体情况编写自然而清晰的注释。注释应该根据代码的实际情况提供必要的上下文和额外的信息，而不仅仅是填充模板。

通过遵循这些最佳实践，可以编写出清晰、易读、易于维护的Java Doc注释。这样可以帮助其他开发者更好地理解和使用代码，提高代码的质量和可维护性。

# 七、总结

本文介绍了如何写好Java Doc注释。

首先概述了Java Doc的定义和作用，强调了它在代码开发过程中的重要性。

然后，详细介绍了Java Doc的基本规范，包括注释格式、注释标签和文档结构。

接着，给出了模块和包注释、类和接口注释、方法注释以及字段注释的内容和示例。

此外，还列举了一些常见的Java Doc错误，并给出了相应的建议。最后，推荐了一些工具和插件，以及Java Doc的最佳实践。

通过编写规范的Java Doc注释，我们可以提供准确的代码说明和参考，帮助其他开发者更好地理解和使用代码。良好的注释可以提高代码的可读性和可维护性，使代码更易于理解和维护。在开发过程中，合理使用Java Doc可以促进团队协作和开发高质量的代码。

希望本文能够帮助你写好Java Doc注释，提升代码的质量和可维护性。让我们一起努力，写出更好的Java代码！

祝你变得更强!

编辑 (opens new window)
#JavaDoc
上次更新: 2023/08/16
Java历代版本新特性
聊聊classpath及其资源获取

← 聊聊classpath及其资源获取→

最近更新
01
Spring表达式语言（SpELl）
02-11
02
Spring中的验证、数据绑定和类型转换
01-30
03
Spring中的资源访问：Resource接口
01-29
更多文章>
Theme by Vdoing | Copyright © 2018-2025 京ICP备2021021832号-2 | MIT License