JavaDoc 使用详解

概述

JavaDoc主要用于描述类、方法的功能及目的。

官网地址

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

JavaDoc注解汇总

注解	描述
@author	作者标识
@version	版本号
@return	对函数返回值的描述
@deprecated	标识过期API（为了保证兼容性，仍可用，但不推荐用）
@throws	构造函数或方法会抛出的异常
@exception	同@throws
@see	引用，查看相关的内容，如类，方法，变量等，必须顶头写
{@link 包.类#成员}	引用，同@see，但可写在任意位置
{@value}	对常量注释，如果其值包含在文档中，通过改标签引用常量的值
{@code}}	{@code text}将文本标记为code，会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名，都需要使用@code进行标记
@param	说明方法的参数
@inheritDoc	用于继承父类中的Javadoc，父类的文档注释，被继承到了子类

描述中使用到的HTML标签

标签	描述
<p>	换行
<pre>	保留文本格式，即保留空格和换行符
<a>	超链接
<ul>	列表
<i>	斜体
<blockquote>	标记引用

JavaDoc注解(由JDK定义) - 类

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

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

示例：

package com.sijing.tset;

/**
 * The {@code String} class represents character strings. All
 * string literals in Java programs, such as {@code "abc"}, are
 * implemented as instances of this class.
 * <p>
 * Strings are constant; their values cannot be changed after they
 * are created. String buffers support mutable strings.
 * Because String objects are immutable they can be shared. For example:
 * <blockquote><pre>
 *     String str = "abc";
 * </pre></blockquote><p>
 * is equivalent to:
 * <blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
 * <p>
 * The class {@code String} includes methods for examining
 * individual characters of the sequence, for comparing strings, for
 * searching strings, for extracting substrings, and for creating a
 * copy of a string with all characters translated to uppercase or to
 * lowercase. Case mapping is based on the Unicode Standard version
 * specified by the {@link java.lang.Character Character} class.
 * <p>
 * The Java language provides special support for the string
 * concatenation operator (&nbsp;+&nbsp;), and for conversion of
 * other objects to strings. String concatenation is implemented
 * through the {@code StringBuilder}(or {@code StringBuffer})
 * class and its {@code append} method.
 * String conversions are implemented through the method
 * {@code toString}, defined by {@code Object} and
 * inherited by all classes in Java. For additional information on
 * string concatenation and conversion, see Gosling, Joy, and Steele,
 * <i>The Java Language Specification</i>.
 *
 * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
 * or method in this class will cause a {@link NullPointerException} to be
 * thrown.
 *
 * <p>A {@code String} represents a string in the UTF-16 format
 * in which <em>supplementary characters</em> are represented by <em>surrogate
 * pairs</em> (see the section <a href="Character.html#unicode">Unicode
 * Character Representations</a> in the {@code Character} class for
 * more information).
 * Index values refer to {@code char} code units, so a supplementary
 * character uses two positions in a {@code String}.
 * <p>The {@code String} class provides methods for dealing with
 * Unicode code points (i.e., characters), in addition to those for
 * dealing with Unicode code units (i.e., {@code char} values).
 *
 * @author  Lee Boynton
 * @author  Arthur van Hoff
 * @author  Martin Buchholz
 * @author  Ulf Zibis
 * @see     java.lang.Object#toString()
 * @see     java.lang.StringBuffer
 * @see     java.lang.StringBuilder
 * @see     java.nio.charset.Charset
 * @since   JDK1.0
 */
public class JavaDocDemo {}

• @link 快速链接到指定代码（ctrl + 点击快速跳转）

  // 完全限定的类名
  {@link java.lang.Character}
  
  // 当前类已经导入该类时，可省略包名
  {@link String}
  
  // 省略类名，表示指向当前的某个方法
  {@link #length()}
  
  // 包名.类名.方法名(参数类型)
  {@link java.lang.String#charAt(int)}
  

• @code {@code text} 将文本标记为code，code内部不会进行html解析，一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。

  {@code "abc"}
  

• @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>
  

• @version 标注当前版本

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

• @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 {}
  

• @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>> {}
  

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

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

• @deprecated：标识过期API（为了保证兼容性，仍可用，但不推荐用）

JavaDoc注解(由JDK定义) - 方法

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

  /**
  * @param str the {@code CharSequence} to check (may be {@code null})
  */
  public static boolean containsWhitespace(@Nullable CharSequence str) {}
  

• @return：后接返回值的描述

  /**
  * @return {@code true} if the {@code String} is not {@code null}, its
  */
  public static boolean hasText(@Nullable String str){}
  

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

  /**
  * @exception IllegalArgumentException if <code>key</code> is null.
  */
  public static Object get(String key) throws IllegalArgumentException {}
  

• @throws 用于描述方法可能抛出的异常

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

• @see：用法与用在类上相同

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

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

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

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

使用Ecplise生成JavaDoc

TIPS：-encoding UTF-8 -charset UTF-8，可以解决 编码GBK的不可映射字符”问题。