Javadoc自动生成帮助文档【荐】.pdfVIP

JAVADOC ：自动生成你的程序开发文档 当初学习编程序的时候，就从来没有想过要给自己写的那几个程序编写一份完整的文档，所 有的注释都仅仅是为了自己当时能够想起这段代码到底是干什么的，没有人想过这些代码的 升级、共享问题。但是，开始做商业软件之后，一切都变了，尤其是大型的团队开发项目中。 大家也许注意到了，java 的API 文档总是紧紧跟随着JSDK 的版本的提高而保持着最新的 状态。试想一下，手工维护这么复杂的文档可能吗？当然不可能，这一切都是javadoc 这个 小程序的功劳（当然也有java 类库作者们做程序注释的一份功劳）。API 文档就是用它根 据最新的源代码自动生成的，一切都是这么容易——只需要你把本来就要写的注释写得更规 范一些，再稍微详细一些。然而，大家似乎好像根本就没有意识到它的存在，很少有人会用 它来为自己的程序生成文档。不知道，你现在是否对它有了兴趣？好吧，下面我们就开始这 个令人轻松的自动文档生成之旅。 【如何插入注释】 javadoc 为你生成代码不是凭空来的，也不是它会自动分析你的代码——每个人都有自己的 代码风格，如果要进行分析翻译恐怕还是机器码更容易生成百倍。它的分析机制依赖于你按 照规范为你的代码添加应有而足够的注释。只有你老老实实写注释，才有可能把以前需要做 双份的工作一次做了。 Javadoc 工具可以从下列对象中提取出信息： · 包。 · 公共类。 · 公共接口。 · 公共或者受保护的方法。 · 公共或者受保护的变量/常数。 针对每一种特性，你都应该提供一条注释。每一条注释都要以/**打头，以*/结尾。在每条 /** …… */文档注释可包括任意格式的文字。它的第一个句子应该是一个总结性的语句， javadoc 会自动把它提出来制作总结页。当然，这里你完全可以使用一些HTML 的记号，例 如I表示斜体；...表示等宽的“打印机”字体；B表示粗体；甚至用包括一副图象等等。（但 是不要使用类似于title的标题格式的标记，或者水平分隔线等，它们会和文档自己的格式 发生冲突）然后在后面接上一些特殊的“标记” 。每个标记以@开头，例如@author 或者 @param 等等。 加入在注释中包含了指向其它文件的其它文件的链接的话（例如你的插图和图片），需要将 那些文件放置在名为doc-files 的子目录中。javadoc 会将这些目录以及其中的文件从源目录 复制到文档目录。下面我们分类解释一下我们可能会比较常用的一些标记。 ■常规注释 下面这些标记可以在所有文档注释中使用。 Ø @since 版本 该标记可以生成一个注释表明这个特性（类、接口、属性或者方法等）是在软件的哪个版本 之后开始提供的。 Ø @deprecated 类、属性、方法名等 这个标记可以增加一条注释，指出相应的类、方法或者属性不再应该使用。javadoc 仅将首 句复制到概览部分和索引中。后面得句子还可以解释为什么不鼓励使用它。有时候，我们也 推荐另外一种解决办法，例如： @deprecated Use theAnotherMethod 或者使用{@link}标记给一个推荐的连接关于它的使用我们将马上介绍。 Ø @see 链接 这个标记在“See also” （参见）小节增加一个超链接。这里的链接可以是下面几项内容： · package.class#member label 添加一个指向成员的锚链接，空格前面是超链接的目标，后 面是显示的文字。注意分隔类和它的成员的是#而不是点号，你可以省略包名或者连类名也 一块省略，缺省指当前的包和类，这样使注释更加简洁，但是#号不能省略。label 是可以省 略的。 · label 这个不用解释了吧。 · Text 这个直接在“See also”中添加一段没有链接的文字。 Ø {@link 链接目标 显示文字} 其实准确的说，link 的用法和see 的用法是一样，see 是把链接单列在参见项里，而link 是 在当前的注释中的任意位置直接嵌入一段带超级链接的文字。 ■为类和接口添加注释 类或者接口的注释必须在所有import 语句的后面，同时又要位于class 定义的前面。除了 上面所说的常规标记以外，你还可以在类注释中使用如下标记： Ø @author 作者名 当使用author 标记时，用指定的文本文字在生成的文档中添加“Author” （作者）项。文档注 释可以包含多个@author 标记。可以对每个@author 指定一个或者多个名字。当然你同样 可以使用多个作者标记，但是它们必须放在一块儿。 Ø @versio