JavaSE——day6如何制作一个简单的类说明书

为什么要做说明书?

    在我们面向对象编程思想中,我们是一个指挥着,所以我们需要做的只是对类的调用。如果制作一个类工具供我们的伙伴使用,那么我们至少应该告诉我们的伙伴这个类是干什么用的、怎么使用这个类中的方法、还有这个类的一些基本信息。这会大大提高我们面向对象变成的效率。
        

如何制作说明书?

        我们首先要考虑的是,我们需要一些具有什么有关联的方法。比如说,我们需要制作一个关于数组的类,那么这个类可以实现的功能可以有遍历、求数组中的最大值、索引、按降序排序、按升序排序等等。在我们明确了我们需要的类的功能后,我们在类中将这些功能分别创建为不同的方法。这些在我们面向对象的部分已经知道,那么如何在说明书中说明这些方法的作用和用法就是我们这篇文章关注的问题。

javadoc如何使用

        在使用javadoc程序生成说明书之前,我们需要确保我们的计算机上已经安装了jdk( Java 语言的软件开发工具包)。没有安装的话我们需要到java官网下载免费的jdk,目前教新的是1.8和1.9。根据自己的系统选择32位/64位,下载完成后安装jdk。安装完成后我们需要配置环境变量。
        配置环境变量的过程:右键点击我的电脑选择属性--->高级系统设置--->环境变量。在系统变量那里找到Path,选择编辑--->新建,将我们安装的jdk文件夹下bin文件夹的绝对路径添加到环境变量中,如下图:

            在系统变量中我们新建一个javaclass的系统变量,将jdk文件夹下的lib目录的绝对路径加到。如图:
点击确定即可,这样我们的jdk安装及环境变量就配置好了。

编写一个需要说明的类的实例

        这是我参考老师demo写的关于array类的实例:

package arraytool;
/**
 * 这是针对数组操作的一个工具,该工具提供了数组遍历,数组求最大值,索引,顺序排序的功能
 * @author malaganguo
 * @version V1.0
 */

public class ArrayTool {

	private ArrayTool() {
		//将ArrayTool私有化
	}
	/**
	 * 这是数组遍历的方法
	 * @param arr	是一个int类型的数组arr[]
	 */
	public static void printTool(int[] arr) {
		
		System.out.print("[");
		
		for(int i = 0 ; i < arr.length ; i ++) {
			if(i == arr.length-1) {
				System.out.println(arr[i] + "]");
			}else {
				System.out.print(arr[i] + ", ");
			}
		}
	}
	
	/**
	 * 这是求数组中最大值的方法
	 * @param arr  是一个int类型的数组arr[]
	 * @return	返回的就是最大值
	 */
	public static int getMax(int[] arr) {
		int max = arr[0] ;
		for(int i = 0 ; i < arr.length ; i ++) {
			if(arr[i] > max) {
				max = arr[i];
			}
		}
		return max;
	}
	
	/**
	 * 这是一个查找元素在数组中第一次出现的索引,找到则返回该索引,没有找到则返回-1
	 * @param arr 是一个int类型的数组arr[]
	 * @param value 需要被查找的元素
	 * @return 如果查到了返回的是该索引,没有返回-1
	 */
	public static int getIndex(int[] arr , int value) {
		int index = -1;
		for(int i = 0 ; i < arr.length ; i ++) {
			if(value == arr[i]) {
				return i;
			}
		}
		return index;
	}
	
	/**
	 * 这是一个将数组中的元素按照从大到小排列的方法,不打印
	 * @param arr 是一个int类型的数组arr[]
	 */
	public static void arrayRank(int[] arr) {
		int temp = arr[0] ; 
		for(int i = 0 ; i < arr.length/2 ; i ++) {
			if(arr[i] < arr[i+1]) {
				temp = arr[i];
				arr[i]  = arr[i+1] ;
				arr[i+1] = temp;
			}
		}
	}
}

这是我写的测试类,测试代码的结果是否正确:
public class Test {
	public static void main(String[] args) {
		int[] arr = {12,33,42,32,11,1};
		
		ArrayTool.printTool(arr);
		int index = ArrayTool.getIndex(arr, 11);
		System.out.println("该索引是" + index);
		ArrayTool.arrayRank(arr);
		ArrayTool.printTool(arr);
	}
}

我们编写说方法明使用的注释是:
/**

*    这里写的是说明
*   @param arr 这里写的是对参数arr的说明

*   @return 这里写的是对返回值的说明
*/

这个注释可以用/**然后回车直接得到。
     类之前的注释是我们对这个类的说明,@author malaganguo 是标出作者是malaganguo(就是我哈哈哈),@version V1.0是标出我们给出的版本V1.0,还有很多的东西可以在输入@以后自动填充。

    每个成员方法之前的注释是我们对每个方法的说明,@param + 参数名(一般会自动填充)+对参数的说明 , @return + 对返回值的说明,等等等等,这些都是我们对方法的说明。


生成说明书的过程

    首先我们在我们想创建说明书的文件夹中创建一个txt文件,将文件名改为我们的类名,后缀改成java。然后打开dos命令窗,快捷键win+R--->cmd,进入我们说明书文件夹的路径,用javadoc -d direction -version -author ArrayTool.java回车即可完成对说明书的创建,就会在该目录中创建一个说明书文件夹,里面有许多html文件。
打开文件夹中的与类同名html文件就可以看到说明书了,如下图:

这样就生成了html版的文档说明书。

    这些作者信息(-author),版本信息(-version)等的附加指可有可无的,根据需求增删。我们输入一个javadoc错误指令后(或者只输入javadoc)就会有关于所有关于javadoc正确指令的使用指南。

以上这些只是关于说明书的基本制作,因为本人的java基础有限,后续的学习完se后希望可以写出一本完整的说明书。大笑

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值