乐趣区

关于java:Java文档注释全攻略


正文 :正文起到对代码标注和解释的作用,如果你去看看 JDK 源码,会发现他们有许多的正文,而且正文是比代码还要多的,可见为代码增加正文是十分重要的,写好正文能让他人更加容易看懂你的代码,正文能够分为以下三种。

(一)单行正文

应用 // 进行正文:

// 阿平好帅 

(二)多行正文

应用 /**/ 进行正文:

/** 阿平是真的帅 /


(三)文档正文

应用 /* / 进行正文:

/** 
    阿平也太帅了吧
*/

文档正文次要是用来生成 java 开发文档 javadoc 的,生成的开发文档和 Java 自身的 API 帮忙文档是一样的,也就是对你所写的类进行解释阐明,所以它还须要搭配一些文档标记,进行解释阐明,而且在文档正文中能够应用 HTML 语言,jdk 源码中有大量的文档正文,所以弄懂文档正文能够帮忙你更好的看懂源码。

文档正文通常还会配合 HTML 标签进行应用,比拟罕用的标签有 \<p>\<pre> 等标签,p 标签用于示意段落,pre 标签可用于显示计算机源码。

留神 :pre 标签中如果有小于号、大于号、例如泛型 在生产 javadoc 时会报错。


1、文档标记

(1)通用的文档标记

以下文档标记在类、办法、变量和常量上都常常应用。

  1. @link:用于疾速链接到相干代码,应用格局:{@link 包名. 类名 #办法名 ( 参数类型)}

    // 齐全限定的类名
    {@link java.util.Collections}
    
    // 省略包名,只写类名
    {@link String}
    
    // 省略类名,示意指向以后的某一个办法
    {@link #toString()}
    
    // 齐全限定办法名,包名. 类名. 办法名 (参数类型)
    {@link java.lang.String#charAt(int)}
  2. @code:将文本标记为代码款式文本,个别在 Javadoc 中只有波及到类名或者办法名,都须要应用 @code 进行标记,应用格局:{@code text},其会被解析为 text

    // 标记类名
    {@code ArrayList}
    
    // 标记办法名
    {@code isEmpty}
    
    // 标记某个代码关键字
    {@code null}

(2)类上罕用文档标记

  1. @param:如果一个类反对泛型时,能够通过 @param 来解释泛型的类型

    /**
      @param <E> the type of elements in this list  
    */
  1. @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>
    
  1. @see : 另请参阅的意思,个别用于标记与本类相关联的类,该标注能够用在类或办法上。

    /**
     * @see IntStream
     * @see LongStream
     * @see DoubleStream
     * @see <a href="package-summary.html">java.util.stream</a>
     * /
    
  2. @since:示意从以下版本开始有这个类,标记文件创建时我的项目过后对应的版本,前面能够跟版本号或是工夫。

    // 跟版本号,以下是 ArrayList 类里的标记,阐明从 jdk1.2 开始就有该类了
    /*
       * @since   1.2
    **/
    // 跟工夫
    /**
    * @since 20 April 2021
    */
  3. @version:用于标记以后类版本,默认为 1.0

     /**
     * @version 1.0
     */

以上是类上罕用的文档标注,类上的文档格局如下:

  1. 概要形容:通常用一段话简要的形容该类的根本内容。
  2. 详细描述:通常用几大段话详细描述该类的性能与相干状况。
  3. 文档标注:用于标注该类的作者、工夫、版本、参略等信息。

以下是 String 类的中文档标注的事例:

/**
 * 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. For additional information on string
 * concatenation and conversion, see <i>The Java&trade; Language Specification</i>.
 *
 * <p> Unless otherwise noted, passing a {@code null} 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).
 *
 * <p>Unless otherwise noted, methods for comparing Strings do not take locale
 * into account.  The {@link java.text.Collator} class provides methods for
 * finer-grain, locale-sensitive String comparison.
 *
 * @implNote The implementation of the string concatenation operator is left to
 * the discretion of a Java compiler, as long as the compiler ultimately conforms
 * to <i>The Java&trade; Language Specification</i>. For example, the {@code javac} compiler
 * may implement the operator with {@code StringBuffer}, {@code StringBuilder},
 * or {@code java.lang.invoke.StringConcatFactory} depending on the JDK version. The
 * implementation of string conversion is typically through the method {@code toString},
 * defined by {@code Object} and inherited by all classes in Java.
 *
 * @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   1.0
 * @jls     15.18.1 String Concatenation Operator +
 */
public final class String
    implements java.io.Serializable, Comparable<String>, CharSequence {}

(3)办法上罕用文档标记

  1. @param:该文档标记前面写办法的参数名,再写参数形容。

    /**
    * @param str 
    * the {@code CharSequence} to check (may be {@code null})
    */
    public static boolean containsWhitespace(@Nullable CharSequence str) {}
    
  2. @return:该文档标记前面写返回值得形容。

    /**
    * @return {@code true} if the {@code String} is not {@code null}, its
    */
    public static boolean hasText(@Nullable String str){}
  3. @throws:该文档标记前面写异样的类型和异样的形容,用于形容该办法可能抛出的异样。

    /**
    * @throws IllegalArgumentException when the given source contains invalid encoded sequences
    */
    public static String uriDecode(String source, Charset charset){}
    
  4. @exception:该标注用于形容办法签名 throws 对应的异样。

    /**
    * @exception IllegalArgumentException if <code>key</code> is null.
    */
    public static Object get(String key) throws IllegalArgumentException {}
  5. @see:可用在类与办法上,示意参考的类或办法。

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

以上是办法上罕用的文档标注,办法上的文档格局如下:

  1. 概要形容:通常用一段话简要的形容该办法的根本内容。
  2. 详细描述:通常用几大段话详细描述该办法的性能与相干状况。
  3. 文档标注:用于标注该办法的参数、返回值、异样、参略等信息。

以下是 String 类中 charAt 办法的示例:

/**
     * Returns the {@code char} value at the
     * specified index. An index ranges from {@code 0} to
     * {@code length() - 1}. The first {@code char} value of the sequence
     * is at index {@code 0}, the next at index {@code 1},
     * and so on, as for array indexing.
     *
     * <p>If the {@code char} value specified by the index is a
     * <a href="Character.html#unicode">surrogate</a>, the surrogate
     * value is returned.
     *
     * @param      index   the index of the {@code char} value.
     * @return     the {@code char} value at the specified index of this string.
     *             The first {@code char} value is at index {@code 0}.
     * @exception  IndexOutOfBoundsException  if the {@code index}
     *             argument is negative or not less than the length of this
     *             string.
     */
    public char charAt(int index) {}

(4)变量和常量上的文档标准

变量和常量上用的比拟多的文档标记是 @link 和 @code,次要正文该常量或变量的根本用法和相干内容。

以下是示例:

/**
     * The value is used for character storage.
     *
     * @implNote This field is trusted by the VM, and is a subject to
     * constant folding if String instance is constant. Overwriting this
     * field after construction will cause problems.
     *
     * Additionally, it is marked with {@link Stable} to trust the contents
     * of the array. No other facility in JDK provides this functionality (yet).
     * {@link Stable} is safe here, because value is never null.
     */
    private final byte[] value;

2、生成帮忙文档

首先先展现下我写的文档正文代码:

HelloWorld.java

package demo2;
/**
 * <p> 这是一个测试 javadoc 的类
 * 
 * @author codepeace
 * @version 1.0
 * @since  1.8
 *
 */
public class HelloWorld {
    String name;
    
    /**
     * 
     * @param name
     * @return name 
     * @throws Exception
     * {@code name} 
     */
    public String test(String name)throws Exception{return name;}
}

Doc.java

package demo2;
/**
 * <p> 这是一个测试 javadoc 的类
 * 
 * @author codepeace
 * @version 1.0
 * @since  1.8
 *
 */
public class Doc {
    String name;
    
    /**
     * 
     * @param name
     * @return name 
     * @throws Exception
     * {@code name} 
     */
    public String test(String name)throws Exception{return name;}
}

(1)应用命令行的形式

  1. 用 wiodow 关上 cmd 终端,而后进入要编译的 java 文件目录的门路中,如下所示:

  1. 输出命令:javadoc -encoding UTF-8 -charset UTF-8 \*.java,就能将你的 java 文件编译成帮忙文档。
  • -encoding 是编码格局,-charset 是字符集格局,须要查看你文件的编码格局,能够通过关上记事本查看编码格局。

  1. 编译胜利后你后发现以后门路下会多出很多文件,咱们须要的文件是 index.html 文件。

  1. 点开后为如下款式,至此帮忙文档生成结束。

(2)应用 IDE 工具的形式

  • 应用 idea 生成 javadoc 文档
  1. 关上 idea,点击 Tools-> Generate JavaDoc,这样会关上生成 javadoc 文档的配置页面。

  1. 配置 javadoc 文档输入详情:

    1. 抉择要输入文档的范畴,抉择是整个我的项目还是模块还是单个文件。
    2. 文档要输入门路。
    3. 抉择哪些类型的办法或参数能够生成文档。
    4. Locale 抉择地区,这个决定了文档的语言,中文就是 zh_CN。
    5. 传入 JavaDoc 的参数,个别写 -encoding UTF-8 -charset UTF-8,示意编码格局。

  1. 点击确定,运行无误后,关上你所抉择的文档输入门路后,抉择 index.html,就是所输入的 javadoc 文档。


  • 应用 eclipse 生成 javadoc 文档
  1. 关上 eclipse,点击 Project-> Generate JavaDoc,这样会关上生成 javadoc 文档的配置页面。

  1. 配置以下 javadoc 文档输入详情,后点击 next

    1. 抉择要输入成文档的文件或模块
    2. 抉择哪些类型的办法或参数能够生成文档
    3. 文档要输入门路。

  1. 设置文档名后,点击 next

  1. 设置编码格局 个别写 -encoding UTF-8 -charset UTF-8,设置 jre 版本,而后点击实现,在方才设置的输入门路中找到 index.html 即可。

  1. 留神点:eclipse 的默认编码不是 UTF-8,所以要将其批改为 UTF-8,批改办法如下:

    关上 eclipse,点击 Window-> Preferences->Workspace,将默认的 GBK 编码改为 UTF- 8 即可。



更多精彩内容敬请关注微信公众号:【平兄聊 Java】

退出移动版