正文：正文起到对代码标注和解释的作用，如果你去看看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】