Java Doc--文档注释--写法/使用

朴灿烈づ我的快乐病毒、 2023-09-30 09:02 8阅读 0赞

原文网址：

## 简介 ##

**说明**

本文介绍Java Doc（文档注释）的用法。

**官网**

[https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html][https_docs.oracle.com_javase_7_docs_technotes_tools_windows_javadoc.html]

## Java Doc注解 ##

<table> 
 <tbody> 
 <tr> 
 <td style="vertical-align:top;"> 标签 </td> 
 <td style="vertical-align:top;"> 描述 </td> 
 <td style="vertical-align:top;"> 示例 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @author </td> 
 <td style="vertical-align:top;"> 标识一个类的作者 </td> 
 <td style="vertical-align:top;"> @author description </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @deprecated </td> 
 <td style="vertical-align:top;"> 指名一个过期的类或成员 </td> 
 <td style="vertical-align:top;"> @deprecated description </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> {@docRoot} </td> 
 <td style="vertical-align:top;"> 指明当前文档根目录的路径 </td> 
 <td style="vertical-align:top;"> Directory Path </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @exception </td> 
 <td style="vertical-align:top;"> 标志一个类抛出的异常 </td> 
 <td style="vertical-align:top;"> @exception exception-name explanation </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @version </td> 
 <td style="vertical-align:top;"> 指定版本 </td> 
 <td style="vertical-align:top;"> @version info </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> {@inheritDoc} </td> 
 <td style="vertical-align:top;"> 从直接父类继承的注释 </td> 
 <td style="vertical-align:top;"> Inherits a comment from the immediate surperclass. </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> {@link} </td> 
 <td style="vertical-align:top;"> 插入一个到另一个主题的链接 </td> 
 <td style="vertical-align:top;"> {@link name text} </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> {@linkplain} </td> 
 <td style="vertical-align:top;"> 插入一个到另一个主题的链接，但是该链接显示纯文本字体 </td> 
 <td style="vertical-align:top;"> Inserts an in-line link to another topic. </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @param </td> 
 <td style="vertical-align:top;"> 说明一个方法的参数 </td> 
 <td style="vertical-align:top;"> @param parameter-name explanation </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @return </td> 
 <td style="vertical-align:top;"> 说明返回值类型 </td> 
 <td style="vertical-align:top;"> @return explanation </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @see </td> 
 <td style="vertical-align:top;"> 指定一个到另一个主题的链接 </td> 
 <td style="vertical-align:top;"> @see anchor </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @serial </td> 
 <td style="vertical-align:top;"> 说明一个序列化属性 </td> 
 <td style="vertical-align:top;"> @serial description </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @serialData </td> 
 <td style="vertical-align:top;"> 说明通过writeObject( ) 和&nbsp;writeExternal( )方法写的数据 </td> 
 <td style="vertical-align:top;"> @serialData description </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @serialField </td> 
 <td style="vertical-align:top;"> 说明一个ObjectStreamField组件 </td> 
 <td style="vertical-align:top;"> @serialField name type description </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @since </td> 
 <td style="vertical-align:top;"> 标记当引入一个特定的变化时 </td> 
 <td style="vertical-align:top;"> @since release </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @throws </td> 
 <td style="vertical-align:top;"> 和 @exception标签一样. </td> 
 <td style="vertical-align:top;"> The @throws tag has the same meaning as the @exception tag. </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> {@value} </td> 
 <td style="vertical-align:top;"> 显示常量的值，该常量必须是static属性。 </td> 
 <td style="vertical-align:top;"> Displays the value of a constant, which must be a static field. </td> 
 </tr> 
 </tbody> 
</table>

## 写在类上面的JavaDoc ##

写在类上的文档标注一般分为三段：

*  第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
 *  第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
 *  第三段：文档标注，用于标注作者、创建时间、参阅类等信息

### 第一段：概要描述 ###

单行示例：

package org.springframework.jdbc.core;
    /**
     * Simple adapter for {@link PreparedStatementSetter} that applies a given array of arguments.
     *
     */
    public class ArgumentPreparedStatementSetter implements PreparedStatementSetter, ParameterDisposer {
    }

多行示例：

package java.lang;
 /**
 * The {@code Long} class wraps a value of the primitive type {@code
 * long} in an object. An object of type {@code Long} contains a
 * single field whose type is {@code long}.
 *
 * In addition, this class provides several methods for converting
 * a {@code long} to a {@code String} and a {@code String} to a {@code
 * long}, as well as other constants and methods useful when dealing
 * with a {@code long}.
 *
 * Implementation note: The implementations of the "bit twiddling"
 * methods (such as {@link #highestOneBit(long) highestOneBit} and
 * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are
 * based on material from Henry S. Warren, Jr.'s Hacker's
 * Delight, (Addison Wesley, 2002).
 *
 * @author Lee Boynton
 * @author Arthur van Hoff
 * @author Josh Bloch
 * @author Joseph D. Darcy
 * @since JDK1.0
 */
 public final class Long extends Number implements Comparable<Long> {
 }

#### @link ####

**作用**

用于快速跳转到相关代码

**用法**

{@link 包名.类名#方法名(参数类型)}

当包名在当前类中已经导入了包名可以省略。

可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名.方法名。

使用此文档标记的类或者方法，可用按住Ctrl键+鼠标单击快速跳到相应的类或者方法上。

解析成html其实就是使用包名.类名\#方法名(参数类型)

**示例**

// 完全限定的类名
    {@link java.nio.charset.CharsetEncoder}
    
    // 省略包名
    {@link String} and {@link StringBuilder}
    
    // 省略类名，表示指向当前的某个方法
    {@link #equals(Object)}
    
    // 包名.类名#方法名(参数类型)
    {@link java.lang.Long#toString(long)}

#### @code ####

**作用**

将文本标记为code，这样会被解析成text。

将文本标记为代码样式的文本，在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式。

一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。

**用法**

\{@code text\}

### 第二段：详细描述 ###

详细描述一般用一段或多段来详细描述类的作用，详细描述中可以使用html标签，如下：

<table> 
 <tbody> 
 <tr> 
 <td> 标签 </td> 
 <td> 描述 </td> 
 </tr> 
 <tr> 
 <td> &lt;p&gt; </td> 
 <td> 换行 </td> 
 </tr> 
 <tr> 
 <td> &lt;pre&gt; </td> 
 <td> 保留文本格式，即保留空格和换行符 </td> 
 </tr> 
 <tr> 
 <td> &lt;a&gt; </td> 
 <td> 超链接 </td> 
 </tr> 
 <tr> 
 <td> &lt;ul&gt; </td> 
 <td> 列表 </td> 
 </tr> 
 <tr> 
 <td> &lt;i&gt; </td> 
 <td> 斜体 </td> 
 </tr> 
 <tr> 
 <td> &lt;blockquote&gt; </td> 
 <td> 标记引用 </td> 
 </tr> 
 </tbody> 
</table>

详细描述和概要描述中间通常有一个空行来分割， 实例如下

### 第三段：文档标注 ###

用于标注作者、创建时间、参阅类等信息。

#### @param ####

**说明**

一般类中支持泛型时会通过@param来解释泛型的类型。

**示例**

package java.util;
 /**
  * @param <E> the type of elements in this list
  *
  */
 public interface List<E> extends Collection<E> {}

#### @author ####

**说明**

详细描述后面一般使用@author来标记作者，如果一个文件有多个作者来维护就标记多个@author，@author后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址)

**示例**

// 纯文本作者
 @author Rod Johnson
 
 // 纯文本作者，邮件
 @author Igor Hersht, igorh@ca.ibm.com
 
 // 超链接邮件 纯文本作者
 @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
 
 // 纯文本邮件
 @author shane_curcuru@us.ibm.com
 
 // 纯文本 组织
 @author Apache Software Foundation
 
 // 超链接组织地址 纯文本组织
 @author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>

#### @see ####

**说明**

@see 一般用于标记该类相关联的类,@see即可以用在类上，也可以用在方法上。

**示例**

/**
  * @see IntStream
  * @see LongStream
  * @see DoubleStream
  * @see <a href="package-summary.html">java.util.stream</a>
  * /
 public interface Stream<T> extends BaseStream<T, Stream<T>> {}

#### @since ####

**说明**

@since 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间。

**示例**

package java.util.stream;
 
 /**
 * @since 1.8
 */
 public interface Stream<T> extends BaseStream<T, Stream<T>> {}

package org.springframework.util;
    
    /**
    * @since 16 April 2001
    */
    public abstract class StringUtils {}

#### @version 版本 ####

**作用**

@version用于标记当前版本，默认为1.0

**示例**

package com.sun.org.apache.xml.internal.resolver;
    /**
     * @version 1.0
     */
    public class CatalogManager {}

## 写在方法上的JavaDoc ##

写在方法上的文档标注一般分为三段：

*  第一段：概要描述
    
     *  通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
 *  第二段：详细描述
    
     *  通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束
 *  第三段：文档标注
    
     *  用于标注参数、返回值、异常、参阅等

### 第一段：概要描述 ###

与上边的相同： “写在类上面的JavaDoc” => 第一段：概要描述

### 第二段：详细描述 ###

与上边的相同： “写在类上面的JavaDoc” => 第二段：详细描述

### 第三段：文档标注 ###

#### @param ####

**说明**

@param 后面跟参数名，再跟参数描述。

**示例**

/**
     * @param str the {@code CharSequence} to check (may be {@code null})
     */
    public static boolean hasText(@Nullable CharSequence str) {
        return (str != null && str.length() > 0 && containsText(str));
    }

#### @return ####

**说明**

@return 跟返回值的描述

**示例**

/**
     * @return {@code true} if the {@code CharSequence} is not {@code null},
     * its length is greater than 0, and it does not contain whitespace only
     */
    public static boolean hasText(@Nullable CharSequence str) {
        return (str != null && str.length() > 0 && containsText(str));
    }

#### @throws ####

**说明**

@throws 异常类型 异常描述 , 用于描述方法内部可能抛出的异常

**示例**

/**
     * @throws IllegalArgumentException when the given source contains invalid encoded sequences
     */
    public static String uriDecode(String source, Charset charset) {}

#### @exception ####

**说明**

@exception 用于描述方法签名throws对应的异常

**示例**

package com.sun.jmx.remote.security;
    /**
     * @exception LoginException if the logout fails.
     */
    public boolean logout() throws LoginException {}

#### @deprecated ####

**说明**

@deprecated 用于标注一个类或成员已过期,通常配合\{@link\}使用

**示例**

/**
    * @deprecated as of 5.0.4, in favor of {@link Locale#toLanguageTag()}
    */
    @Deprecated
    public static String toLanguageTag(Locale locale) {
        return locale.getLanguage() + (hasText(locale.getCountry()) ? "-" + locale.getCountry() : "");
    }

#### @see ####

**说明**

@see 既可以用来类上也可以用在方法上，表示可以参考的类或者方法

**示例**

/**
    * @see java.net.URLDecoder#decode(String, String)
    */
    public static String uriDecode(String source, Charset charset) {}

#### @value ####

**说明**

\{@value\} 用于标注在常量上用于表示常量的值。

**简介**

/** 默认数量 {@value} */
    private static final Integer QUANTITY = 1;

#### @inheritDoc ####

**说明**

@inheritDoc 用于注解在重写方法或者子类上，用于继承父类中的Javadoc

1.  基类的文档注释被继承到了子类
2.  子类可以再加入自己的注释（特殊化扩展）
3.  @return @param @throws 也会被继承

## JavaDoc示例 ##

spring-core中的StringUtils

package org.springframework.util;
 /**
 * Miscellaneous {@link String} utility methods.
 *
 * Mainly for internal use within the framework; consider
 * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
 * for a more comprehensive suite of {@code String} utilities.
 *
 * This class delivers some simple functionality that should really be
 * provided by the core Java {@link String} and {@link StringBuilder}
 * classes. It also provides easy-to-use methods to convert between
 * delimited strings, such as CSV strings, and collections and arrays.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @author Keith Donald
 * @author Rob Harrop
 * @author Rick Evans
 * @author Arjen Poutsma
 * @author Sam Brannen
 * @author Brian Clozel
 * @since 16 April 2001
 */
 public abstract class StringUtils {
 	/**
 	 * Check that the given {@code CharSequence} is neither {@code null} nor
 	 * of length 0.
 	 * Note: this method returns {@code true} for a {@code CharSequence}
 	 * that purely consists of whitespace.
 	 * <pre class="code">
 	 * StringUtils.hasLength(null) = false
 	 * StringUtils.hasLength("") = false
 	 * StringUtils.hasLength(" ") = true
 	 * StringUtils.hasLength("Hello") = true
 	 * </pre>
 	 * @param str the {@code CharSequence} to check (may be {@code null})
 	 * @return {@code true} if the {@code CharSequence} is not {@code null} and has length
 	 * @see #hasText(String)
 	 */
 	public static boolean hasLength(@Nullable CharSequence str) {
 		return (str != null && str.length() > 0);
 	}
 }

## 其他网址 ##

[Java 文档注释 | 菜鸟教程][Java _ _]

[Javadoc 使用详解\_monday的博客-CSDN博客\_javadoc][Javadoc _monday_-CSDN_javadoc]

[https_docs.oracle.com_javase_7_docs_technotes_tools_windows_javadoc.html]: https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
[Java _ _]: https://www.runoob.com/java/java-documentation.html
[Javadoc _monday_-CSDN_javadoc]: https://blog.csdn.net/vbirdbest/article/details/80296136