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

原文网址：

简介

说明

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

官网

https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html

Java Doc注解

标签

描述

示例

@author

标识一个类的作者

@author description

@deprecated

指名一个过期的类或成员

@deprecated description

{@docRoot}

指明当前文档根目录的路径

Directory Path

@exception

标志一个类抛出的异常

@exception exception-name explanation

@version

指定版本

@version info

{@inheritDoc}

从直接父类继承的注释

Inherits a comment from the immediate surperclass.

{@link}

插入一个到另一个主题的链接

{@link name text}

{@linkplain}

插入一个到另一个主题的链接，但是该链接显示纯文本字体

Inserts an in-line link to another topic.

@param

说明一个方法的参数

@param parameter-name explanation

@return

说明返回值类型

@return explanation

@see

指定一个到另一个主题的链接

@see anchor

@serial

说明一个序列化属性

@serial description

@serialData

说明通过writeObject( ) 和writeExternal( )方法写的数据

@serialData description

@serialField

说明一个ObjectStreamField组件

@serialField name type description

@since

标记当引入一个特定的变化时

@since release

@throws

和 @exception标签一样.

The @throws tag has the same meaning as the @exception tag.

{@value}

显示常量的值，该常量必须是static属性。

Displays the value of a constant, which must be a static field.

写在类上面的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}.
 *
 * <p> 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}.
 *
 * <p>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 <i>Hacker's
 * Delight</i>, (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标签，如下：

标签

描述

换行

保留文本格式，即保留空格和换行符



超链接


 
 

  
  

列表


  
  

斜体


  
  

   
   

标记引用

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

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

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

### @param

**说明**

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

**示例**

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

### @author

**说明**

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

**示例**

    // 纯文本作者
    @author Rod Johnson
    
    // 纯文本作者，邮件
    @author Igor Hersht, igorh@ca.ibm.com
    
    // 超链接邮件 纯文本作者
    @author 
   
   Ovidiu Predescu
    
    // 纯文本邮件
    @author shane_curcuru@us.ibm.com
    
    // 纯文本 组织
    @author Apache Software Foundation
    
    // 超链接组织地址 纯文本组织
    @author 
   
    Apache Jakarta Turbine

### @see

**说明**

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

**示例**

    /**
    ?* @see IntStream
    ?* @see LongStream
    ?* @see DoubleStream
    ?* @see 
   
   java.util.stream
    ?* /
    public interface Stream extends BaseStream
  
  
 
 

其他网址

Java 文档注释 | 菜鸟教程

Javadoc 使用详解_monday的博客-CSDN博客_javadoc