2024-04-19| Java： Documented注解学习 JavaDoc

news2025/4/20 15:13:35

在 Java 中，@Documented 是一个元注解（meta-annotation），用于标记其他注解，表明这些注解应该被包含在 JavaDoc 文档中。以下是关于 @Documented 注解的作用的简要说明：

作用

记录注解信息到 JavaDoc：当一个注解被 @Documented 标记时，使用该注解的代码元素（类、方法、字段等）的注解信息会出现在生成的 JavaDoc 文档中。
没有 @Documented 的注解在生成 JavaDoc 时不会出现在文档中。

使用场景

自定义注解：如果你定义了一个自定义注解，并且希望它的使用情况被记录在 JavaDoc 中，就需要使用 @Documented。
提高文档可读性：对于需要向开发者展示注解信息的场景，@Documented 确保注解的存在和作用被清晰记录。

代码示例

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

// 定义一个自定义注解，使用 @Documented
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface MyAnnotation {
    String value() default "default";
}

// 使用自定义注解
@MyAnnotation("example")
public class MyClass {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

在生成 JavaDoc 时，@MyAnnotation("example") 会出现在 MyClass 的文档中。如果没有 @Documented，则不会显示。

注意事项

必须与 @Retention 配合：@Documented 通常需要注解的 @Retention 策略为 RetentionPolicy.RUNTIME 或 RetentionPolicy.CLASS，否则注解在运行时或编译时不可见，文档化无意义。
只影响 JavaDoc：@Documented 不会影响注解的运行时行为，仅影响文档生成。
内置注解示例：Java 中的许多标准注解（如 @Deprecated、@Override）都使用了 @Documented，因此它们的信息会出现在 JavaDoc 中。

总结

@Documented 的核心作用是确保自定义注解的使用信息被记录到 JavaDoc 中，适合需要公开文档化的场景。使用时需结合 @Retention 和 @Target 等元注解以确保正确行为。

如果有更具体的问题或需要进一步解释，请告诉我！

Javadoc 是 Java 提供的一种工具和文档生成规范，用于从 Java 源代码中提取注释、类、方法、字段等信息，生成 API 文档（通常为 HTML 格式）。它是开发者和团队分享代码功能、接口说明的重要工具。

核心概念

Javadoc 注释：

使用 /** ... */ 格式的特殊注释，称为 Javadoc 注释。
通常包含描述信息和特定的 Javadoc 标签（如 @param、@return、@throws 等）。

示例：

/**
 * 计算两个整数的和。
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两数之和
 * @throws IllegalArgumentException 如果输入不合法
 */
public int add(int a, int b) {
    if (a < 0 || b < 0) throw new IllegalArgumentException("负数不可用");
    return a + b;
}

Javadoc 工具：
- 随 JDK 提供，命令行工具（如 javadoc）解析源代码中的 Javadoc 注释，生成 HTML 格式的 API 文档。
- 运行示例：javadoc -d docs MyClass.java，会在 docs 目录生成文档。
生成的文档：
- 包含类、接口、方法、字段的说明，以及继承关系、方法参数、返回值、异常等信息。
- 常用于生成项目 API 参考文档，类似 Java 官方 API 文档（https://docs.oracle.com/en/java/javase/17/docs/api/）。

Javadoc 标签

常用标签包括：

@param：描述方法参数。
@return：描述返回值。
@throws 或 @exception：描述抛出的异常。
@author：作者信息。
@version：版本信息。
@see：引用其他类或方法。
@since：指明从哪个版本开始引入。

与 `@Documented` 的关系

如果一个自定义注解使用了 @Documented 元注解，那么该注解在代码中的使用情况（如 @MyAnnotation）会出现在 Javadoc 生成的文档中。
没有 @Documented 的注解不会显示在 Javadoc 中，即使它被应用到类或方法上。

使用场景

API 文档生成：为库或框架生成用户友好的文档。
团队协作：帮助开发者理解代码的功能和用法。
开源项目：提供清晰的接口说明，方便用户使用。

运行 Javadoc

编写带有 Javadoc 注释的代码。

使用命令：

javadoc -d <输出目录> -sourcepath <源代码目录> <包名或文件>

查看生成的 HTML 文件（如 index.html）。

注意事项

注释清晰：Javadoc 注释应简洁、准确，避免歧义。
编码问题：生成文档时可能需要指定编码，如 -encoding UTF-8。
私有成员：默认不生成私有方法/字段的文档，可用 -private 选项包含。

示例输出

对于上面的 add 方法，Javadoc 可能生成如下 HTML 内容：

<h3>add</h3>
<p>计算两个整数的和。</p>
<ul>
  <li><b>Parameters:</b> a - 第一个整数, b - 第二个整数</li>
  <li><b>Returns:</b> 两数之和</li>
  <li><b>Throws:</b> IllegalArgumentException - 如果输入不合法</li>
</ul>