乐趣区

关于程序员:简单了解下Java的注释

jiezi

与大多数程序设计语言一样，Java 中的正文也不会呈现在可执行程序中。因而，能够在源程序中依据须要增加任意多的正文，而不用放心可执行代码会收缩。在 Java 中，有 3 中标记正文的形式。

第一种形式 //，其正文内容要放到 // 的前面且到本行开端完结。

System.out.println("Hello, World!"); // 'Hello, World!' output

第二种形式 /**/，当正文比拟长时，能够应用 /* 和 */ 将正文括起来。

/*
    多行正文。*/

第三种形式 /***/，这种正文是文档正文。从 /** 开始，以 */ 完结。

/**
    文档正文。*/

文档正文次要负责形容类、域、办法、结构器等，并可能被 javadoc 工具抽取生成 HTML 文档并与源文件保留在一个中央。当批改源代码后，从新运行 javadoc 就能够放弃源文件与文档的一致性。

文档正文中呈现以 @ 结尾的标记称为 Javadoc 文档标记。如下所示：

标记 形容
@author 标记作者，多个作者应用多个 @author。例如，@author Mony
@version 标记以后版本的形容。例如，@version 1.0
@since 标记引入个性的版本形容。例如，@since version 1.7.1。
@deprecated 标记类、办法或变量不再应用。
@see 在该标记后增加与之关联项。可用在类、办法上。
@param 标记参数形容。泛型类中对泛型的类型进行形容；办法中后跟参数名，在对参数进行形容。
@return 该标记在办法中跟返回值形容。
@throws 标记抛出的异样类型，并对异样进行形容。
@exception 与 @throws 标签用法一样。
@link 标记为链接，用于指向其它类或办法。
@value 标记常量的值，而且该常量必须具备 static 属性。
@code 标记文本为代码款式。

而除了标记外，还能够应用 HTML 标签如 <p> 分隔段落，<ul> 标记列表和 <li> 标记列表选项，但不要应用 <h1> 或 <hr> 等与文档格局起抵触的标签。

/**
 * Arithmetic
 *
 * <p>
 *     This is a class that describes four operations
 * </p>
 *
 *
 * @author hireny
 * @version 1.0
 */
public class Arithmetic {

    /**
     * This is a method to do addition
     *
     * @param a summand
     * @param b addend
     * @return Value after operation
     */
    public static int add(int a, int b) {return a + b;}

    /**
     * This is a method to do subtraction
     * @param a minuend
     * @param b subtraction
     * @return Value after operation
     */
    public static int sub(int a, int b) {return a - b;}

    /**
     * This is a method to do multiplication
     *
     * @param a multiplicand
     * @param b multiplier
     * @return Value after operation
     */
    public static int mult(int a, int b) {return a * b;}

    /**
     * This is a method to do division
     *
     * @param a divisor
     * @param b divisor
     * @return Value after operation
     */
    public static int div(int a, int b) {return a / b;}

    /**
     * This is a method of division and remainder
     *
     * @param a divisor
     * @param b divisor
     * @return Value after operation
     */
    public static int rem(int a, int b) {return a % b;}
}

定义完一个类中的文档正文后，能够在该源文件的目录下运行 javadoc Arithmetic.java 生成该源文件的 HTML 文档，如果与零碎默认的 GBK 编码抵触，能够应用其它编码集如 javadoc Arithmetic.java -encoding UTF-8 -charset UTF-8。上面是运行后生成的文件。

而如果想要对一个包生成正文，就须要在每个包下增加 package.html 或者 package-info.java；也能够对包中源文件做一个概述性的正文。如下所示：

但这样生成的文档会放在当前目录下，造成包下文件的凌乱，因而，在生成文档时，要应用 -d 选项减少文档目录 javadoc -d docDirectory *.java。

javadoc 命令还有很多性能，并且生成文档也能够应用 IDE 提供好的工具来生成 Javadoc 文档。

更多内容请关注公众号「海人为记」

退出移动版