JAVA基础：自动生成你的程序开发文档

文章作者 100test 发表时间 2007:03:14 17:01:10
来源 100Test.Com百考试题网

项目到了尾声，大家都开始头疼——又要写文档了……是的，我们大多数人都不是从正规的Programer训练出来的。当初学习编程序的时候，就从来没有想过要给自己写的那几个程序编写一份完整的文档，所有的注释都仅仅是为了自己当时能够想起这段代码到底是干什么的，没有人想过这些代码的升级、共享问题。但是，开始做商业软件之后，一切都变了，尤其是大型的团队开发项目中。

大家也许注意到了，java的API文档总是紧紧跟随着JSDK的版本的提高而保持着最新的状态。试想一下，手工维护这么复杂的文档可能吗？当然不可能，这一切都是javadoc这个小程序的功劳（当然也有java类库作者们做程序注释的一份功劳）。API文档就是用它根据最新的源代码自动生成的，一切都是这么容易——只需要你把本来就要写的注释写得更规范一些，再稍微详细一些。然而，大家似乎好像根本就没有意识到它的存在，很少有人会用它来为自己的程序生成文档。不知道，你现在是否对它有了兴趣？好吧，下面我们就开始这个令人轻松的自动文档生成之旅。



【如何插入注释】



JAVADOC为你生成代码不是凭空来的，也不是它会自动分析你的代码——每个人都有自己的代码风格，如果要进行分析翻译恐怕还是机器码更容易生成百倍。它的分析机制依赖于你按照规范为你的代码添加应有而足够的注释。只有你老老实实写注释，才有可能把以前需要做双份的工作一次做了。

Javadoc工具可以从下列对象中提取出信息：

· 包。

· 公共类。

· 公共接口。

· 公共或者受保护的方法。

· 公共或者受保护的变量/常数。

针对每一种特性，你都应该提供一条注释。每一条注释都要以/**打头，以*/结尾。在每条/**
…… */文档注释可包括任意格式的文字。，它的第一个句子应该是一个总结性的语句，javadoc会自动把它提出来制作总结页。当然，这里你完全可以使用一些HTML的记号，例如...表示斜体；...表示等宽的“打印机”字体；...表示粗体；甚至用包括一副图象等等。