JBuilder2005创建开发文档之Javadoc - 编程入门网

JBuilder2005创建开发文档之Javadoc

虽然软件工程中把详细设计作为软件项目的一个重要的阶段，但在实践中往往没有得到落实。并不是这个阶段不重要，而是实施有很大的困难，因为软件需求是天生的易动症患者，好不容易详细设计出来后，需求已和当初的版本大相径庭，而花费巨大，精雕细琢的详细设计已变成昨日黄花了。另一方面，有一些功能实现往往要等到真正编码时才能想到更好的方法，毕竟设计时是"凭空想象"，而编码时才是"实践操作"，所以在编码时对原设计进行调整常常在所难免。

详细设计文档是源代码实现上的描述，但在物理上则是和源代码文件分离的，两者间的一致性很容易被打破，维持两者一致性代价常常是项目正常周期无法承受的。各种"自文档"或"直接文档"的技术应运而生，Javadoc就是Java的自文档技术，即通过"寄生"在源代码文件中的注释信息产生帮助文档，这种帮助文档本身也就是详细设计文档。由于程序代码和注释信息在同一个文件中，在更改程序时相应调整注释则是举手之劳的事，两者间的一致性很容易得到保障。

作为一名Java程序员，想必多少看过JDK的API帮助文档，JBuilder自带的JDK1.4的帮助文档位于<JBuilder 安装目录>/doc/jdk_docs.jar，它包含了JDK的Javadoc文档，你可以通过诸如winRAR等解压软件将jdk_doc.jar解压到某个目录下，解压后jdk_docs/java/api目录中的文档就是JDK的Javadoc文档。双击打开目录下的index.html文件，你将看到如下的页面

图1 JDK的Javadoc文档

网页分为三个帧，左上角的帧是包的列表，左下角的帧是包中类的列表，而右边主窗口帧是类的API说明页面。

类API说明页面顶部有一个导航条，方便链接到一些常用的页面，这些常见的页面包括：

·Overview：所有包的说明列表，每个包对应表中一行说明。

·Package：包中所有类或接口的说明列表，每个类或接口对应表中一行说明。

·Class：标明为当前类，其上并无链接。

·Use：类的所有关联类：包括继承关系，依赖关系，关联关系等。

·Tree：以层次结构列出包中类继层级关系，通过这个列表，可以对类探本溯源，下面是java.applet包Applet类的继承用实现树。

图2 以层次结构列出包中的类

·Deprecated：所有过期的类、接口、值域、方法、构造函数。

·Index：索引页面，将JDK中所有的类、接口、常量、方法都以字母顺序进行索引，借此页面可以快速定位到所需的帮助内容，其页面如下：

图3 以索引方式组织

JBuilder2005创建开发文档之Javadoc(2)

·Help：关于如何使用Javadoc文档的帮助信息，你可以通过这个文档了解更多使用Javadoc的方法。

每一个类和接口都对应一个Javadoc文档，类和接口的Javadoc文档所占比例最大、内容最丰富，它是使用这些类和接口的直接参考文档。由于类比接口包含了更多的内容，所以我们仅介绍类的文档。一个典型的类Javadoc文档包括以下的内容：

·导航条：在文档头部和尾部都有导航条，方便快速链接到常用的页面，提供了上一页和下一页的链接，并且提供了在定位到本页中不同部分的锚链接。

·类的继承关系：类的继承树，类实现的接口以及类的子类。通过这些信息可以从纵向了解类的关联关系。

·类的简要说明：类的简要描述信息，描述类的功用。

·内部类的列表：列出类中所定义的内部类。

·类值域摘要：所有的protected和public的值域，每个值域对应一句说明。

·类构造方法摘要：所有的protected和public的成员构造方法，每个构造方法对应一句说明。

·类成员方法摘要：所有的protected和public的成员方法，每个方法对应一句说明。

·类继承方法列表：承继父类方法的列表。

·类值域详细说明：protected和public的值域的详细说明及关联链接。

·类构造方法详细说明：protected和public的构造方法的详细说明，方法入参、返回值、抛出异常说明及关联链接。

·类成员方法详细说明：protected和public的成员方法的详细说明，方法入参、返回值、抛出异常说明及关联内容的链接。

JBuilder提供了许多支持Javadoc的功能，这些功能包括：

·可通过快捷键创建类、接口、方法、值域及构造函数的注释结构体，注释结构体中包含了和源码对应的标签。

·诱导录入Javadoc标签的JavadocInsight。

·可通过快捷键添加@todo标签并可以浏览这些标签。

·报告并修复和源代码冲突的Javadoc注释。

·通过Archiver Builder创建整个工程的Javadoc文档。

·创建自定义的Javadoc标签

·用Doc浏览器浏览程序文件的Javadoc文档

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务，公司网站：http://www.lingzhong.cn 为了给广大客户了解更多的技术信息，本技术文章收集来源于网络,凌众科技尊重文章作者的版权，如果有涉及你的版权有必要删除你的文章，请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息，谢谢!