------- android培训、java培训、期待与您交流！ ----------
上一篇我们自己创建了一个数组工具类，可以对数组进行各种操作。那么既然是工具类，就不仅要服务于我们自己，还应该可以帮助他人实现功能，这才是工具类的意义所在。当我们把由源代码编译得来的工具类字节码文件（“.class”）文件发给别人用的时候，这个类里面都有什么方法，如何调用这些方法是无法通过该文件看出来的（实际上，即使将字节码文件打开，也都是乱码），这时候就需要帮助文档了（也称为API文档，是Application Program Interface的缩写，应用程序接口）。
在讲如何创建帮助文档之前，我们先说一说另外一个大家容易犯错的地方。当我们从网上获取到了别人定义好的工具类字节码文件（以上篇ArrayTools类为例）后，将其保存到某个路径下，例如“d:\myclass”路径下，然后通过下面的代码调用其中的方法，
代码1：
class ArrayToolsDemo
{
<span style="white-space:pre"> </span>public static void main(String[] args)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>int[] arr = {45, 12, 56, 71, 34, 90, 22, 4};
<span style="white-space:pre"> </span>int max = ArrayTools.getMax(arr);
<span style="white-space:pre"> </span>System.out.println("max = "+max);
<span style="white-space:pre"> </span>}
}max = 90
其中我们需要注意的是，如果ArrayTools类和ArrayToolsDemo不在同一个文件夹下时，应先设置classpath，命令行命令为“setclasspath=.;d\myclass”。细心的朋友可能会注意到，在路径前有一个“.”，表示当前目录，如果把“.”去掉，那么虚拟机只会在指定目录寻找需要的类字节码文件，而在“d:\myclass”路径下却并没有ArrayToolsDemo字节码文件，就会报错。
通过上述设置并能够正常使用工具类以后，我们聊聊帮助文档的创建。就像我们在前面说的一样， 帮助文档就像是一个程序的说明书，里面会有这个类的各种信息，比如，类中都有哪些对外提供的方法，包括方法名、返回值类型、以及对这个方法功能的简单描述，甚至可能会有调用这个方法的具体代码。我们还是以ArrayTools类为例。
代码2：
public class ArrayTools
{
<span style="white-space:pre"> </span>/**
<span style="white-space:pre"> </span>这是一个可以对整型数组进行操作的工具类
<span style="white-space:pre"> </span>该类中提供了获取最值、排序、打印数组等方法。
<span style="white-space:pre"> </span>@author Akx
<span style="white-space:pre"> </span>@version v1.0
<span style="white-space:pre"> </span>*/
<span style="white-space:pre"> </span><span style="white-space:pre"> </span>/**
<span style="white-space:pre"> </span>空参数构造函数
<span style="white-space:pre"> </span>*/
<span style="white-space:pre"> </span>private ArrayTools(){}
<span style="white-space:pre"> </span>//最大值
<span style="white-space:pre"> </span>/**
<span style="white-space:pre"> </span>获取一个整型数组中的最大值
<span style="white-space:pre"> </span>@param arr 接收一个整型数组
<span style="white-space:pre"> </span>@return 返回该数组中的最大值。
<span style="white-space:pre"> </span>*/
<span style="white-space:pre"> </span>public static int getMax(int[] arr)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>int max = arr[0];
<span style="white-space:pre"> </span>for(int x=1; x<arr.length; x++)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>if(max< arr[x])
<span style="white-space:pre"> </span>max = arr[x];
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>return max;
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>//最小值
<span style="white-space:pre"> </span>/**
<span style="white-space:pre"> </span>获取一个整型数组中的最小值
<span style="white-space:pre"> </span>@param arr 接收一个整型数组
<span style="white-space:pre"> </span>@return 返回该数组中的最小值。
<span style="white-space:pre"> </span>*/
<span style="white-space:pre"> </span>public static int getMin(int[] arr)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>int min = arr[0];
<span style="white-space:pre"> </span>for(int x=1; x<arr.length; x++)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>if(min> arr[x])
<span style="white-space:pre"> </span>min = arr[x];
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>return min;
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>/**
<span style="white-space:pre"> </span>给整型数组进行选择排序
<span style="white-space:pre"> </span>@param arr 接收一个整型数组
<span style="white-space:pre"> </span>*/
<span style="white-space:pre"> </span>//选择排序
<span style="white-space:pre"> </span>public static void selectSort(int[] arr)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>for(int x=0; x<arr.length-1; x++)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>for(int y=x+1; y<arr.length; y++)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>if(arr[x]> arr[y])
<span style="white-space:pre"> </span>swap(arr,x, y);
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>}<span style="white-space:pre"> </span><span style="white-space:pre"> </span>//交换两元素的位置
<span style="white-space:pre"> </span>//交换两元素的位置
<span style="white-space:pre"> </span>/**
<span style="white-space:pre"> </span>交换数组中两个元素的位置
<span style="white-space:pre"> </span>@param arr 接收一个整型数组
<span style="white-space:pre"> </span>@param x 需要交换位置的元素
<span style="white-space:pre"> </span>@param y 需要交换位置的另一个元素
<span style="white-space:pre"> </span>*/
<span style="white-space:pre"> </span>private static void swap(int[] arr, int x, int y)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>arr[x] = arr[x] ^ arr[y];
<span style="white-space:pre"> </span>arr[y] = arr[x] ^ arr[y];
<span style="white-space:pre"> </span>arr[x] = arr[x] ^ arr[y];
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>//打印数组
<span style="white-space:pre"> </span>/**
<span style="white-space:pre"> </span>打印数组中的元素。打印形式：[element1, element2, element3, ...]
<span style="white-space:pre"> </span>@param arr 接收整型数组
<span style="white-space:pre"> </span>*/
<span style="white-space:pre"> </span>public static void printArray(int[] arr)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>System.out.print("[");
<span style="white-space:pre"> </span>for(int x=0; x<arr.length; x++)
<span style="white-space:pre"> </span>{
<span style="white-space:pre"> </span>if(x!= arr.length-1)
<span style="white-space:pre"> </span>System.out.print(arr[x]+",");
<span style="white-space:pre"> </span>else
<span style="white-space:pre"> </span>System.out.println(arr[x]+"]");
<span style="white-space:pre"> </span>}
<span style="white-space:pre"> </span>}
}类描述格式：
/**
类描述
@author 作者名
@version 版本号
*/
方法描述格式如下：
/**
方法描述
@param 参数名 参数描述
@return 返回值描述
*/
@author、@version、@param和@return是可以被帮助文档生成工具识别的标签，分别代表类的作者、类的版本号、参数和返回值。可能有的朋友会说，我们可以直接使用新版本，没有必要标明版本号。之所以标明版本号是因为，新版本可能会有一些bug，导致无法正常使用，在这种情况下，我们应该先提供旧版使用户能够正常使用，然后修改bug，再提供最新版，此时就应表明版本号，让用户知道这是老的版本。@param和@return分别表示调用方法时需要传入的参数名和返回值的含义。
至此，工具类的注释文档就定义完毕了，下面开始创建帮助文档。这里我们要用到除了javac和java以外的第三个工具——javadoc。命令行命令为：“javadoc–d myhelp –author –version ArrayTools.java”，其中，“-d”表示要将帮助文档生在到指定目录；myhelp为目录名（自定义）；-author和-version分别显示作者和版本号；最终加上需要创建帮助文档的类文件。注意，如果要想为一个类创建帮助文档，必须将这个类定义为“public”。指定目录下没有“myhelp”文件夹，就会自动创建一个同名文件夹。
创建完毕以后，就会在指定目录下的“myhelp”文件夹下看到很多网页文件。打开名为“index”的文件，就可以查看类及其方法的所有信息了。大家会发现，在方法摘要中没有swap方法，这是因为该方法是私有方法，在生成帮助文档就会略过。只有方法的访问权限被定义为public何protected才能够生成帮助文档。关于protected访问权限后面的博客中会涉及到。如果想要将构造函数也显示在帮助文档中，就需要将构造方法的访问权限定义为public。
小知识点1：
构造方法的权限和所在类的权限是一致的。如果类的访问权限是public，那么默认的构造方法也是public访问权限；相反，如果类的访问权限不是public，那么构造方法的访问权限也就不是public了。总之一句话，构造方法的访问权限是随着类的变化而变化的。
当然，Java也为我们提供了一个帮助文档，其中包含Java中所有包中的类及其方法的信息，方便程序使用。
扫一扫
478
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
