如何为我们的程序编写开发文档——Java文档注释

Java文档注释

Java文档注释是用于生成Java API文档的注释，通过在程序中的类、属性、方法部分加上注释，就可以用javadoc命令生成漂亮的API文档，是程序员进阶的必备技能。

    /** comment for class */
    public class Test{
        /** comment for a attribute */
        int number;

        /** comment for a method */
        public void myMethod(){ ......}
    }

注意，文档注释只说明紧跟其后的类、属性或者方法。
Javadoc文档生成命令为：

    javadoc -d 文档存放目录 -author -version 源文件名.java -encoding 编码 -charset 字符集
    如：
    javadoc -d d:/Javadoc Test.java -encoding UTF-8 -charset UFT-8

-author和-version可以省略。

文档注释的结构

根据在文档中显示的效果，文档注释分为三部分。举例如下：

    /** 
     * show 方法的简单描述。
     * show方法详细说明第一行

     * show方法详细说明第二行
     * @param b 输入的字符串
     * @return 返回“Hello，”加上输入的字符串
     */
    public String show(String b){
        return "Hello,"+b;
    }

第一部分是简述。如下图中被红框框选的部分:

简述部分写在一段文档注释的最前面，第一个点号 (.) 之前 (包括点号).
第二部分是详细说明部分。该部分对属性或者方法进行详细的说明，在格式上没有什么特殊的要求，可以包含若干个点号。它在文档中的位置如下图所示：

这部分文档对应的代码是：

     * show 方法的简单描述。
     * show方法详细说明第一行

     * show方法详细说明第二行

第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。它在文档中的位置：

Javadoc标记

标记	范围	作用
@author	类	标明开发该类的作者
@version	类	标明该类模块的版本
@see	类、属性、方法	参考转向，也就是相关主题
@param	方法	对方法中参数的说明
@return	方法	对方法返回值的说明
@exception	方法	对方法可能抛出的异常说明

总结

除上面所写之外，还有javadoc命令等详细参数没有介绍，请自行在命令行中使用help命令查看。
关于生成Java文档，通过命令行进行生成通常只做演示的作用，我们开发所使用的IDE如：IntelliJ IDEA、Eclipse等均集成了文档生成功能，只需要我们把文档注释写好，然后点击按钮即可。