Android修炼系列（八），你真的会写注释吗?

本节主要介绍下我们常用的 javadoc tag ，虽然内容比较简单，但若正确使用，真的能使我们的代码高大上不少。不仅如此，只要我们按照Javadoc 注释规则，在编码完成后，Javadoc 也能够帮我们从源代码中生成相应的 Html 格式的 API 开发文档。可以点击Oracle规范，我将常用的javadoc tag 根据自己的习惯进行了整理，见下：

tags

在给公共类或公共方法添加注释的时候，第一句话应该是一个简短的摘要。注意左侧不要紧挨 * 号，要有一个空格。如果注释有多个段落，使用< p>段落标记来分隔段落。我们还可使用< tt>标签来让特定的内容呈现出等宽的文本效果。见下：

    /**

     * 第一句话是这个方法的<tt>简短</tt>摘要。

     * 如果这个描述太长，记得换行。

     * 

     * <p>如果多个段落可以这样

     * 当回车的时候与标签首部对齐即可

     */

    public void test(){}

复制代码

如果注释描述里需要包含一个列表，一组选项等，我们可以使用< li>标签来标识，注意标签后不需要空格，见下：

    /**

     * 第一句话是这个方法的简短摘要。

     * 如果这个描述太长，记得换行。

     * 

     * <p>如果多个段落可以这样

     * 

     * <ul>

     * <li>这是列表1

     * <li>这是列表2...

     * 同样回车后与标签对齐即可

     * </ul>

     */

    public void test(){}

复制代码

@param 是用来描述方法的输入参数。注意在方法描述和tag 之间需要插入空白注释行。不需要每个参数param的描述都对齐，但要保证同个param的多行描述对齐。param 的描述不需要在句尾加标点。

    /**

     * 第一句话是这个方法的简短摘要。

     * 如果这个描述太长，记得换行。

     *

     * @param builderTest 添加参数的描述，如果描述很长，

     *                    需要回车，这里需要对齐

     * @param isTest 添加参数描述，不需要刻意与其他param

     *               参数对齐

     */

    public void test(String builderTest, boolean isTest){}

复制代码

@return 是用来描述方法的返回值。要写在@param tag之后，与其他tag 之间不需要换行。@throws 是对方法可能会抛出的异常来进行说明的，通常格式为：异常类名+异常在方法中出现的原因。见下：

    /**

     * 第一句话是这个方法的简短摘要。

     *

     * @param capacity 添加参数描述，不需要刻意与其他param

     *                 参数对齐

     * @return 描述返回值的含义，可以多行，不需要句号结尾

     * @throws IllegalArgumentException 如果初始容量为负

     *         <ul>

     *         <li>这是抛出异常的条件1（非必须），注意<li>格式

     *         </ul>

     * @throws 注意如果方法还存在其他异常，可并列多个

     */

    public int test(int capacity){

        if (capacity < 0)

            throw new IllegalArgumentException("Illegal initial capacity");

        return capacity;

    }

复制代码

@deprecated 用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用旧特性。常与@link 配合，当然@link的使用位置没有任何限制，当我们的描述需要涉及到其他类或方法时，我们就可以使用@link啦，javadoc会帮我们生成超链接：

    /**

     * 第一句话是这个方法的简短摘要。

     * 如果这个描述太长，记得换行。

     * 

     * @deprecated 从2.0版本起不推荐使用，替换为{@link #Test2()}

     * @param isTest 添加参数描述，不需要刻意与其他param

     *               参数对齐

     */

    public void test(boolean isTest){}

复制代码

@link 常见形式见下:

@code 用来标记一小段等宽字体，也可以用来标记某个类或方法，但不会生成超链接。常与@link配合，首次通过@link生成超链接，之后通过@code 呈现等宽字体。

    /**

     * 第一句话是这个方法的简短摘要。

     * 我们可以关联{@link Test}类，随后通过{@code Test}类怎样怎样

     * 也可以标记一个方法{@code request()}

     *

     * @param isTest 添加参数描述，不需要刻意与其他param

     *               参数对齐

     */

    public void test(boolean isTest){}

复制代码

@see 用来引用其它类的文档，相当于超链接，javadoc会在其生成的HTML文件中，将@see标签链到其他的文档上：

    /**

     * 第一句话是这个方法的简短摘要。

     *

     * @param capacity 添加参数描述，不需要刻意与其他param

     *                 参数对齐

     * @return 描述返回值的含义，可以多行，不需要句号结尾

     * @throws IllegalArgumentException 如果初始容量为负

     * @see com.te.Test2

     * @see #test(int)

     */

    public int test(int capacity){

        if (capacity < 0)

            throw new IllegalArgumentException("Illegal initial capacity");

        return capacity;

    }

复制代码

@see形式与@link类似，见下：

@since 用来指定方法或类最早使用的版本。在标记类时，常与@version和@author配合，一个用来指定当前版本和版本的说明信息，一个用来指定编写类的作者和联系信息等。我们也可以通过< pre>来添加一段代码示例。见下：

    /**

     * 第一句话是这个类的简短摘要。

     * <pre>

     *     Test<Test2> t = new Test<>();

     * </pre>

     * 

     * <p>同样可以多个段落。

     * 

     * @param <T> 注意当类使用泛型时，我们需要使用params说明。这时格式需要插入空白行

     *

     * @author mjzuo 123@qq.com

     * @see com.te.Test2

     * @version 2.1

     * @since 2.0

     */

    public class Test<T extends Test2> {

        /**

         * 第一句话是这个方法的简短摘要。

         * 

         * @params capacity 参数的描述

         * @return 返回值的描述

         * @since 2.1

         */

        public int test2(int capacity) {

            return capacity;

        }

    }

复制代码

@inheritDoc 用来从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。如下的test() 方法，会直接继承该类的直接父类的test()方法注释。注意与其他tag 不需要插入空行：

    /**

     * {@inheritDoc}

     * @since 2.0

     */

    public void test(boolean isTest){}

复制代码

@docRoot 它总是指向文档的根目录，表示从任何生成的页面到生成的文档根目录的相对路径。例如我们可以在每个生成的文档页面都加上版权链接，假设我们的版权页面copyright.html 在根目录下：

    /**

     * <a href="{@docRoot}/copyright.html">Copyright</a>

     */

    public class Test {}

复制代码

@hide 当我们使用google提供的Doclava时，可以使用 @hide 来屏蔽我们不想暴露在javaDoc文档中的方法。

    /**

     * {@hide}

     */

    public class Test {}

复制代码

好了，本文到这里，关于常用的javaDoc tag的介绍就结束了。如果本文对你有用，来点个赞吧，大家的肯定也是阿呆i坚持写作的动力。