登录 主页

java 文档注释

2024-09-07 06:00PM

1.文档注释格式

java文档注释(Javadoc)用于生成API文档,它允许开发者为类、方法和字段等添加说明。

1) 所有的java文档注释都以 /** 开头, */ 结尾,通常放在类或方法的声明之前

2) 文档注释覆盖范围包括:类、接口、方法、构造器、成员字段,如果写在其他位置,比如函数内容部,则被视为无效文档注释

3) 每个java文档注释都要和其后对应的类/方法/字段保持同样的缩进

4) java文档注释的内容,支持采用HTML语法规则书写,同时也支持一些额外的辅助标签

在类/方法上的文档标注一般分为三段,顺序如下:

第一段:概要描述,通常用一句话或者一段话简要描述该类的作用,以英文句号结束,这句话会被提取并放到索引目录中。

第二段:详细描述,通常用一段话或者多段话详细描述该类的作用,每段话都以英文句号结束,详细描述中可以使用HTMl标签,如<p>,<pre>,<a>,<li>等标签。

第三段:文档标记,通常用于标注作者,创作时间、参阅类等信息,描述部分和文档标记之间必须空一行。

eg:

/**
 * 这是一个示例类,演示如何使用 Javadoc 注释。
 */
public class Example {

    /**
     * 计算两个整数的和。
     *
     * @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工具可以识别文档注释中的一些特殊标签,这些标签一般以@开头,后跟一个指定的名字,有的也以{@开头,以}结束,javadoc可以识别的标签如下:

@author

说明:用于指明作者或者组织,可以附加邮箱或者超链接,如果有多个作者就用多个标签,适用范围:包、类、接口。

eg:

/**
 * @author xxxx
 * @author xxx@123.com
 * @author <a href="mailto:xxx@123.com">xxxxx</a>
 */

@since

说明:用于指明最早出现在哪个版本,可填版本号或日期,有时也可以表名运行的JDK版本,适用范围:包、类、接口、方法、成员属性、构造器(类似于go语言的struct)

eg:

/**
 * @since 1.4
 * @since 15 April 2001
 * @since JDK1.5
 */

@version

说明:用于指明当前版本号。适用范围:包、类、接口

eg:

/**
 * @version 1.8.3.4
 */

@code

用于将一些关键字或代码片段格式化为代码样式,以便在生成的文档中清晰可读。它通常用于描述某个方法或类时引用代码示例。

eg:

public class Example {

    /**
     * 计算两个整数的和。
     *
     * @param a 第一个整数
     * @param b 第二个整数
     * @return 两个整数的和
     * @code
     * // 示例用法
     * Example example = new Example();
     * int result = example.add(5, 10);
     * System.out.println(result); // 输出 15
     * @endcode
     */
    public int add(int a, int b) {
        return a + b;
    }
}

@code 后面可以跟随代码片段,生成的文档会将其格式化为代码样式。

@endcode 用于表示代码片段的结束,尽管在大多数情况下,可以省略这一行,具体取决于文档生成工具的实现。

@return

说明:对函数返回值的注释。适用范围:方法

/**
 * @return <code>true</code> 执行成功;<code>false</code> 执行失败.
 */

@value

说明:只能用于对常量进行注释,该标签常用于写在字段上的javadoc注释。适用范围:方法、成员属性

eg:

/**
 * Default start value. {@value #START_VALUE}
 */

@throws 和 @exception

说明:用户描述构造函数或方法所会抛出的异常。适用范围:方法、构造器

/**
 * @throws IllegalArgumentException
 *         if {@code fromIndex > toIndex}
 */

@link 、@linkplain 和 @see

说明:用于创建一个超链接到相关代码。

适用范围:包、类、接口、方法、成员属性、构造器

注意事项:

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

2) @link 和 @see的区别在于:@link可以放在某一行中的任意位置;而 @see必须放在某一行中的最开始。

/**
 * xxx {@link java.lang.String#charAt(int)}
 * xxx {@link #sort(Object[])}
 * xxx {@linkplain Comparable natural ordering}
 * @see #deepHashCode(Object[])
 */

@inheritDoc

说明:用于继承父类的 javadoc 注释,父类的文档注释会被拷贝到子类。适用范围:方法

eg:

/**
 * {@inheritDoc}
 * <p>
 * The speed of tiger will be returned.
 * 
 * @return the speed of tiger 
 */

@deprecated

说明:告诉用户该 API 已过时,并且已被哪些新的 API 取代了。用@see或 @link指向新的API。该旧的 API 之所以不删掉,通常是为了兼容性考虑。。适用范围:包、类、接口、方法、成员属性、构造器 

eg:

/**
* @deprecated As of JDK 1.1, replaced by 
* {@link #setBounds(int, int, int, int)}
*/

@serial

说明:说明一个序列化属性。适用范围:方法、成员属性

/**
 * @serial description
 */

@serialData

说明:用于说明通过 writeObject() 和 writeExternal() 方法写的数据。。适用范围:方法、成员属性

/**
 * @serialData description
 */

@serialField

说明:用于说明一个 ObjectStreamField 组件。适用范围:方法、成员属性

/**
 * @serialField name type description
 */

最后,在使用文档注释时,通常会按照如下顺序进行使用。

@author
@version
@param
@return
@exception / @throws
@see
@since
@serial / @serialField / @serialData
@deprecated

3. java api 文档生成方式

使用 Javadoc 工具,可以通过命令行生成 HTML 格式的文档:

javadoc -d doc Example.java

这将创建一个名为 doc 的目录,里面包含生成的 API 文档。

返回>>

登录

请登录后再发表评论。

评论列表:

目前还没有人发表评论