生成帮助文档的步骤及示例（Java程序设计）

Java中提供的文档注释允许开发者在程序中嵌入关于程序的相关信息，用于说明如何使用当前程序。Java提供了javadoc命令，它可以将这些帮助信息提取出来，自动生成HTML格式的帮助文档，从而实现程序的文档化。

文档注释以/**开始，以*/结束。在/**之后的第一行或前几行是关于类、属性和方法的主要描述，接着可以包含一个或多个各种各样@标签。每一个@标签必须在一个新行的开始或者在一行的开始紧跟星号（*）。例如：@author用于标识一个类的作者；@version用于说明版本信息@since说明最早出现在哪个版本；@param描述一个方法的参数；@return描述方法的返回值；@throws描述方法抛出的异常，指明抛出异常的条件。

【例3-13】

设计一个工具类，并提取文档注释来生成帮助文档。

下面设计一个My CircleTool类，类的定义及相关文档注释如图3-28所示。

图3-28　MyCircleTool类

在Eclipse开发环境中生成My Circle Tool类的帮助文档。步骤如下：

步骤1：在菜单栏上选择【Project】下的【Generate Javadoc】选项，如图3-29所示。

图3-29　找到【Generate Javadoc】选项

步骤2：在弹出的对话框中，选择需要生成帮助文档的类、设置帮助文档需要保存的路径，如图3-30所示。

图3-30　选择生成帮助文档的类和保存路径

步骤3：点击【Next】按钮，弹出下一个对话框。根据需要选择配置文档标题，根据需要选择配置Javadoc的变量，根据需要选择需要链接的类，如图3-31所示。

图3-31　配置standard doclet的Javadoc变量

步骤4：点击【Next】按钮，弹出下一个对话框。如果项目采用的是UTF-8编码，需要在额外的Javadoc选项下输入设定参数“-encoding utf-8-charset utf-8”，否则生成的页面上中文注释都是乱码，如图3-32所示。

图3-32　配置Javadoc变量

步骤5：点击【Finish】按钮开始生成帮助文档，在对应的路径下可以找到一系列文件，如图3-33所示。

图3-33　查看生成的文件

步骤6：查看帮助文档。生成的目录中，index.html是整个帮助文档的首页，用浏览器打开即可看到相关类的帮助文档，里面包含类所处的包名、继承关系、功能、属性和方法说明等，如图3-34所示。

图3-34　MyCircleTool的帮助文档

【例3-14】

利用工具类My Circle Tool，计算一个圆的面积和周长。

如果我们拿到工具类（字节码文件，扩展名为.class）和关于该类的帮助文档，那么通过查询帮助文档就可以知道该工具类的用途、相关属性和方法的使用。通过帮助文档，可以知道MyCircle Tool类提供了求面积和周长的方法，并且知道使用这些方法需要的参数及返回值等。利用MyCircle Tool工具类提供的方法如图3-35所示。(www.xing528.com)

图3-35　使用MyCircleTool工具类

项目总结

本项目详细介绍了面向对象的基础知识。首先，介绍了面向对象的编程思想，讲解了对象和类的关系。然后，从类的组成着手依次介绍了成员属性和成员方法，其中构造方法是特殊的成员方法，专门用于构造对象。在类的设计过程中引入了this关键字和static关键字，并利用private关键字实现类的属性封装，介绍了控制访问权限的几个关键字。接着，讲解了匿名对象的使用和单例模式的几种实现方式，设计模式是前人针对特定问题经验的总结，值得认真学习。最后，举例说明如何利用文档注释生成帮助文档。总之，本项目和下一项目都是面向对象程序设计的核心，都是重点，希望能全面掌握。

项目作业

1.判断题。

（1）Java源程序可以定义若干个类，但只能有一个带main方法的主类。　（　）

（2）如果一个Java类没有显式定义构造方法，系统会提供一个缺省的构造方法。　（　）

（3）构造方法的第一条语句如果是super（），则可以省略。　（　）

（4）Java可以使用new关键字来创建一个类的实例（对象）。　（　）

（5）实例方法中不能引用静态变量或直接调用静态方法。　（　）

（6）静态方法中不能使用this，调用实例方法必须先创建对象。　（　）

（7）在方法中，可以将对象作为参数进行传递，传递对象实际是在传递对象的引用。　（　）

（8）声明构造方法时，不能使用private关键字进行修饰。　（　）

（9）类中static关键字修饰的变量或者方法，推荐使用对象的引用变量访问。　（　）

（10）一个类的成员被protected关键字修饰，则该成员只能被同一包下的类访问。　（　）

2.简述类和对象的关系。

3.简述this关键字的用法。

4.从修饰成员属性、成员方法和代码块三方面简述static关键字的用法。

5.简述匿名对象的用法。

6.简述类的四种访问控制权限。

7.按照要求设计一个Student类，并通过测试类测试。

（1）成员属性包括静态变量学校名称，实例变量姓名、年龄和平均分，注意控制权限的使用。

（2）提供无参构造方法和有参构造方法。

（3）分别为不同属性提供getter和setter方法。

（4）提供一个public void show（Student stu）方法用来显示学生的所有信息。

（5）在测试类中分别使用无参构造方法和有参构造方法构造Student对象，通过调用方法修改对象中的成员变量取值，并调用show方法显示该学生对象所有信息。8.上机实践书中出现的案例，可自由发挥修改。