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

在 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，则不会显示。

注意事项

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

总结

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

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

---

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

核心概念

1. 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;
     }
     

2. Javadoc 工具：

   • 随 JDK 提供，命令行工具（如 javadoc）解析源代码中的 Javadoc 注释，生成 HTML 格式的 API 文档。
   • 运行示例：javadoc -d docs MyClass.java，会在 docs 目录生成文档。

3. 生成的文档：

   • 包含类、接口、方法、字段的说明，以及继承关系、方法参数、返回值、异常等信息。
   • 常用于生成项目 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

1. 编写带有 Javadoc 注释的代码。
2. 使用命令：

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

3. 查看生成的 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>

总结

Javadoc 是 Java 生态中用于生成 API 文档的标准工具，通过 /** ... */ 注释和标签提取代码信息，生成结构化的 HTML 文档。它与 @Documented 结合使用时，可确保自定义注解信息也出现在文档中，是开发和文档化的重要组成部分。

如果需要更详细的用法或示例，请告诉我！