javadoc 注解有哪些

JavaDoc 注解概览及代码示例

JavaDoc 是 Java 编程语言的一个文档生成工具，它允许开发者从源代码中提取注释，并将这些注释转换成格式化的文档。JavaDoc 注解是 JavaDoc 工具用来增强文档内容的特殊注释。在本文中，我们将探讨一些常用的 JavaDoc 注解，并提供代码示例以及旅行图和饼状图的可视化表示。

JavaDoc 注解简介

JavaDoc 注解主要用于以下几个方面：

1. 类和接口描述：@deprecated 用于标记过时的类或接口。
2. 方法和构造函数描述：@param 用于描述参数，@return 用于描述返回值，@throws 或 @exception 用于描述可能抛出的异常。
3. 字段描述：@see 用于引用其他类、方法或字段。
4. 包和概述描述：package 用于描述包的文档，overview 用于描述整个项目的概述。

常用 JavaDoc 注解

以下是一些常用的 JavaDoc 注解及其用法：

@deprecated

标记某个元素（类、方法、字段等）已经过时。

登录后复制

/**
 * @deprecated 这个类已经被新版本替代，请使用 {@link NewClass}。
 */
public class OldClass {
    // 类内容
}

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.

@param

描述方法参数。

登录后复制

/**
 * 这个方法计算两个数的和。
 * 
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两个数的和
 */
public int add(int a, int b) {
    return a + b;
}

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.
• 10.

@return

描述方法的返回值。

登录后复制

/**
 * 返回当前时间的毫秒表示。
 * 
 * @return 当前时间的毫秒表示
 */
public long getCurrentTimeMillis() {
    return System.currentTimeMillis();
}

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.

@throws / @exception

描述方法可能抛出的异常。

登录后复制

/**
 * 这个方法尝试打开一个文件，并抛出异常如果文件不存在。
 * 
 * @param fileName 文件名
 * @throws FileNotFoundException 如果文件不存在
 */
public void openFile(String fileName) throws FileNotFoundException {
    // 文件打开逻辑
}

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.
• 9.

@see

引用其他类、方法或字段。

登录后复制

/**
 * 这个类实现了一个简单的计算器。
 * 
 * @see Calculator#add(int, int)
 */
public class Calculator {
    // 类内容
}

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.

package 和 overview

描述包和项目的概述。

登录后复制

/**
 * 这个包包含基本的数学运算类。
 */
package com.example.math;

/**
 * 这个项目是一个简单的计算器应用程序。
 */

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.

旅行图示例

以下是使用 Mermaid 语法表示的旅行图，描述了用户使用 JavaDoc 的过程：

饼状图示例

以下是使用 Mermaid 语法表示的饼状图，展示了不同 JavaDoc 注解的使用频率：

结语

JavaDoc 注解是 Java 编程中不可或缺的一部分，它们帮助开发者生成清晰、有用的文档。通过本文的介绍和示例，我们希望读者能够更好地理解和使用 JavaDoc 注解，从而提高代码的可读性和可维护性。记住，良好的文档是优秀软件的关键组成部分。

原创作者: u_16213357 转载于: https://blog.51cto.com/u_16213357/11549323