用JavaDoc生成项目文档

项目到了尾声，你们都开始头疼——又要写文档了……是的，咱们大多数人都不是从正规的Programer训练出来的。当初学习编程序的时候，就历来没有想过要给本身写的那几个程序编写一份完整的文档，全部的注释都仅仅是为了本身当时可以想起这段代码究竟是干什么的，没有人想过这些代码的升级、共享问题。可是，开始作商业软件以后，一切都变了，尤为是大型的团队开发项目中。
    你们也许注意到了，java的API文档老是牢牢跟随着JSDK的版本的提升而保持着最新的状态。试想一下，手工维护这么复杂的文档可能吗？固然不可能，这一切都是javadoc这个小程序的功劳（固然也有java类库做者们作程序注释的一份功劳）。API文档就是用它根据最新的源代码自动生成的，一切都是这么容易——只须要你把原本就要写的注释写得更规范一些，再稍微详细一些。然而，你们彷佛好像根本就没有意识到它的存在，不多有人会用它来为本身的程序生成文档。不知道，你如今是否对它有了兴趣？好吧，下面咱们就开始这个使人轻松的自动文档生成之旅。

      【如何插入注释】

    JAVADOC为你生成代码不是凭空来的，也不是它会自动分析你的代码——每一个人都有本身的代码风格，若是要进行分析翻译恐怕仍是机器码更容易生成百倍。它的分析机制依赖于你按照规范为你的代码添加应有而足够的注释。只有你老老实实写注释，才有可能把之前须要作双份的工做一次作了。
    Javadoc工具能够从下列对象中提取出信息：
    · 包。
    · 公共类。
    · 公共接口。
    · 公共或者受保护的方法。
    · 公共或者受保护的变量/常数。
    针对每一种特性，你都应该提供一条注释。每一条注释都要以/**打头，以*/结尾。在每条/** …… */文档注释可包括任意格式的文字。，它的第一个句子应该是一个总结性的语句，javadoc会自动把它提出来制做总结页。固然，这里你彻底可使用一些HTML的记号，例如<i>...</i>表示斜体；<tt>...</tt>表示等宽的“打印机”字体；<b>...</b>表示粗体；甚至用<img...>包括一副图象等等。（可是不要使用相似于<h1>的标题格式的标记，或者水平分隔线<hr>等，它们会和文档本身的格式发生冲突）而后在后面接上一些特殊的“标记”。每一个标记以@开头，例如@author或者@param等等。
    加入在注释中包含了指向其它文件的其它文件的连接的话（例如你的插图和图片），须要将那些文件放置在名为doc-files的子目录中。javadoc会将这些目录以及其中的文件从源目录复制到文档目录。下面咱们分类解释一下咱们可能会比较经常使用的一些标记。

    ■常规注释
    下面这些标记能够在全部文档注释中使用。
    ◇ @since 版本
    该标记能够生成一个注释代表这个特性（类、接口、属性或者方法等）是在软件的哪一个版本以后开始提供的。
    ◇ @deprecated 类、属性、方法名等
    这个标记能够增长一条注释，指出相应的类、方法或者属性再也不应该使用。javadoc仅将首句复制到概览部分和索引中。后面得句子还能够解释为何不鼓励使用它。有时候，咱们也推荐另一种解决办法，例如：
    @deprecated Use <tt>theAnotherMethod</tt>
    或者使用{@link}标记给一个推荐的链接关于它的使用咱们将立刻介绍。
    ◇ @see 连接
    这个标记在“See also”（参见）小节增长一个超连接。这里的连接能够是下面几项内容：
    · package.class#member label 添加一个指向成员的锚连接，空格前面是超连接的目标，后面是显示的文字。注意分隔类和它的成员的是#而不是点号，你能够省略包名或者连类名也一块省略，缺省指当前的包和类，这样使注释更加简洁，可是#号不能省略。label是能够省略的。
    · <a href=...>label</a> 这个不用解释了吧。
    · "Text" 这个直接在“See also”中添加一段没有连接的文字。
    ◇ {@link 连接目标 显示文字}
    其实准确的说，link的用法和see的用法是同样，see是把连接单列在参见项里，而link是在当前的注释中的任意位置直接嵌入一段带超级连接的文字。

    ■为类和接口添加注释
    类或者接口的注释必须在全部import语句的后面，同时又要位于class定义的前面。除了上面所说的常规标记之外，你还能够在类注释中使用以下标记：
    ◇ @author 做者名
    当使用author标记时，用指定的文本文字在生成的文档中添加“Author”（做者）项。文档注释能够包含多个@author标记。能够对每一个@author指定一个或者多个名字。固然你一样可使用多个做者标记，可是它们必须放在一起。
    ◇ @version 版本
    这个标记建议一个“版本”条目，后面的文字能够是当前版本的任意描述。
    下面是类注释的一个例子：
/**
 * An implementation of a menu bar. You add <code>JMenu</code> objects to the
 * menu bar to construct a menu. When the user selects a <code>JMenu</code>
 * object, its associated <code>JPopupMenu</code> is displayed, allowing the
 * user to select one of the <code>JMenuItems</code> on it.
 * <p>
 * For information and examples of using menu bars see
 * <a
 href="http://java.sun.com/docs/books/tutorial/uiswing/components/menu.html">How to Use Menus</a>,
 * a section in <em>The Java Tutorial.</em>
 * For the keyboard keys used by this component in the standard Look and
 * Feel (L&F) renditions, see the
 * <a href=doc-files/Key-Index.html#JMenuBar>JMenuBar</a> key assignments.
 * <p>
 * <strong>Warning:</strong>
 * Serialized objects of this class will not be compatible with 
 * future Swing releases. The current serialization support is appropriate
 * for short term storage or RMI between applications running the same
 * version of Swing. A future release of Swing will provide support for
 * long term persistence.
 *
 * @beaninfo
 * attribute: isContainer true
 * description: A container for holding and displaying menus.
 *
 * @version 1.85 04/06/00
 * @author Georges Saab
 * @author David Karlton
 * @author Arnaud Weber
 * @see JMenu
 * @see JPopupMenu
 * @see JMenuItem
 */
    
    ■方法注释
    紧靠在每条方法注释的前面，必须有一个它所描述的那个方法的签名。一样除了使用常规用途的标记之外，还可使用以下针对方法的注释：
    ◇ @param 变量描述
    当前方法须要的全部参数，都须要用这个标记进行解释，而且这些标记都应该放在一块儿。具体的描述（说明）可同时跨越多行，而且可使用html标记。
    ◇ @return 该方法的返回值
    这个标记为当前方法增长一个返回值（“Returns”）小节。一样具体描述支持html并可跨多行。
    ◇ @throws 该方法抛出的异常
    这个标记为当前方法在“Throws”小节添加一个条目，并会自动建立一个超级连接。具体的描述能够跨越多行，一样能够包括html标记。一个方法的全部throws都必须放在一块儿。
    下面是一个方法注释的例子：
    /**
     * Returns the model object that handles single selections.
     *
     * @param ui the new MenuBarUI L&F object
     * @return the <code>SingleSelectionModel</code> property
     * @see SingleSelectionModel
     * @see JComponent#getUIClassID
     * @see UIDefaults#getUI
     */

    ■包和综述注释
    前面的都是针对某一个类、方法等的注释，能够直接放在JAVA源文件中。然而为了生成一个包的注释，必须在每一个包的目录下放置一个名为package.html的文件来对包进行描述。标签<body>....</body>之间的文字都会被javadoc自动提取出来。
    也能够为全部源文件提供一个综述注释，写入名为overview.html文件中，将其放在全部源文件所在的父目录下面。标签<body> .... </body>之间的文字也都会被javadoc自动提取出来，作成文档的Overview

     【如何提取程序文档】

    首先，咱们仍是依照惯例来看看javadoc的基本用法，你能够经过javadoc -help来得到它当前版本的具体设定细节。
    javadoc [options] [packagename] [sourcefiles] [@files]
    参数能够按造任意顺序排列。
    · options 命令行选项。
    · packagenames 一系列包的名字，空格分隔，必须分别制定想要为之创建文档的每个包。Javadoc不递归做用于每个包，也不容许使用通配符。
    · sourcefiles 一系列源文件名，用空格分隔。源文件名能够包括路径和通配符如“*”。
    · @files 以任意次序包含包名和源文件的一个或者多个文件。当在sourcefiles中须要指定的文件太多的时候，就可使用它来简化操做。目标文件是以空格或者回车来进行分隔的源文件名。
    其中经常使用的选项有：
    -d 路径
      指定javadoc保存生成的HTML文件的目的目录，缺省为当前目录。
    -author
      在文档中包含做者信息（默认状况下会被省略）
    -version
      在文档中包含版本信息（在默认状况下会被省略）
    -header header文本
      指定放置在每一个输出文件顶部的页眉文件。该页眉文件将放在上部导航栏的右边，header文本能够包括HTML标记和空格，可是若是这样就必须用引号将它括起。在header中的任何内部引号都不准使用转义。
    -footer footer文本
      指定放置在每一个输出文件底部的脚注文本。脚本将放置在下部导航栏的右边，其它同header同样。
    -bottom text
      指定放置在么个输出文件底部的文本。该文本将放置在页底，位于导航栏的下面。其它同header参数。
    -protected
      只显示受保护的和共有的类及成员，这是缺省状态。
    -public
      只显示公有的类和成员。
    -package
      只显示包、受保护的和公有的类及成员。
    -private
      显示全部的类和成员，若是是内部开发使用的程序文档，这个将很是有用。
    -sourcepath sourcepathlist
      当将包名传递给javadoc的时候，能够指定查找源文件（.java）的搜索路径。但必须注意，只有当用javadoc命令指定包名时才能使用sourcepath选项。若是省略sourcepath，则javadoc使用classpath查找源文件。注意：你须要把sourcepath设置成目标包的源文件所在的目录，例如：你在从c:jproject里有一个包cn.com.linuxaid，你想为它里面的文件生成文档，那么你就必须写成c:jprojectcncomlinuxaid。
    -clathpath clathpathlist
      指定javadoc查找“引用类”的路径，“引用类”是值带文档的类加上它们引用的任何类。javadoc将搜索指定路径的全部子目录。classpathlist能够包含多个路径，它们用分号分隔。

    下面咱们来举一个例子：
    假设，咱们须要在targetdocdir放置咱们生成的文档，须要对c:jproject里的cn.com.linuxaid包内的源文件创建程序文档。那么咱们须要进入c:jprojectcncom（也就是包含了overview.html的目录——假如你提供了它的话）。而后运行 javadoc -d targetdocdir cn.com.linuxaid

    除了javadoc提供了丰富的选项参数来让你定制你所须要生成的程序文档之外，还能够借助doclet来产生任何形式的输出，具体的状况，请仔细阅读联机帮助文档。