javaSE之文档注释

当需要把自己做好的class文件上传以便他人使用的时候，为了让使用者能够清晰的了解这个程序的情况（文件是干什么用的，内里的方法是什么样的，使用者如何调用）

所以就有了文档注释，因为上传的是后缀名为class的文件，而不是可以编译的java文件，所以文档注释是我们写在java文件中的。

文档注释在java文件中是用/***/来实现的，前面是/**中间是正文，后面是*/收尾。

比如，现在有了一个求最大值的程序，为了让使用者能搞清楚情况来调用。如下：

/**

此类是取一个int数组的最大值        //简明概括类的用途

@author 万万没想到                        //介绍作者名        

@version 0.1                                //介绍版本号

*/

public class Max{        //注意让别人调用必须加public公共化，否则无法生成文档注释相关文件。

/**

取数组内的最大值                        //简明概括方法的功用

@param arr 传入一个int数组        //写明参数param的名arr 然后解释传入什么（对参数进行描述）

@return 返回一个int数组的最大值         //对返回值进行描述（若无返回void就不用写）

*/

public static int max(int[] arr){

int max=arr[0];

for(int i=0;i<arr.length;i++){

if(arr[i]>max){

max=arr[i];

}

}

return max;

}

}

通常文档注释开头先注释文档的说明（干什么的），以及作者和版本（也可不写）。

然后单个方法的文档注释写在该方法的前面（这里只写了一个）；

若多个方法注释，比如还有一个求最小值的方法，那就在其方法前再单独文档注释一下。

---------------------------------------------------------

以上这些都写好，开始生成class文件，那使用者是如何调用的呢

调用者打开java安装程序的bin目录，其内有很多exe文件，比如我们之前用的javac.exe编译程序文件，还有运行的java.exe文件等等，

而其中有个javadoc.exe执行程序文件，这个就是用来对文档注释进行提取的程序。

我们可以通过cmd命令行来提取。

首先定位java文件夹的位置，然后输入 ,比如javadoc在E盘java文件夹下

E:\java>javadoc -d newDoc -author -version Max.java

其中 -d newDoc 表示把提取的文档注释文件放入一个叫newDoc的文件夹内，若没有这个文件夹，则会自动创建（在这里，d可以理解为download 加载）

后面的依次是表示 作者和版本号也一并提取的意思，最后是文件名

之后就会看到一个newDoc的多网页文件夹，其中index网页内就是提取后的文档注释了。