项目到了尾声,大家都开始头疼——又要写文档了……是的,我们大多数人都不是从正规的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来产生任何形式的输出,具体的情况,请仔细阅读联机帮助文档。

用JavaDoc生成项目文档的更多相关文章

  1. javadoc 生成帮助文档时,注意以下几点

    参考:http://www.w3school.com.cn/tags/tag_pre.asp javadoc 生成帮助文档时,注意以下几点: 1.函数功能描述的结尾一定要有句号,英文句号或中文句号均可 ...

  2. 使用Docfx生成项目文档

    使用docfx.console生成本项目的文档 使用docfx.console生成其他项目的文档 直接使用docfx.exe生成项目文档 指定配置文档模板   文档地址:http://gitlab.l ...

  3. Maven生成项目文档

    Maven项目可以通过maven-site-plugin插件生成项目文档,无论什么项目都可以生成. 执行命令: mvn site 生成完成的输出目录在${basedir}/target/site文件夹 ...

  4. PowerDesigner(九)-模型文档编辑器(生成项目文档)(转)

    模型文档编辑器 PowerDesigner的模型文档(Model  Report)是基于模型的,面向项目的概览文档,提供了灵活,丰富的模型文档编辑界面,实现了设计,修改和输出模型文档的全过程. 模型文 ...

  5. 使用apidoc生成项目文档

    [1]npm install apidoc -g 全局安装apidoc [2]apidoc -v 查看是否安装成功 [3]apidoc.json apidoc的项目级配置文件,它必须位于整个工程目录顶 ...

  6. PHP的学习--使用PhpDocumentor 2生成API文档

    官网地址:http://www.phpdoc.org/ 项目地址:https://github.com/phpDocumentor/phpDocumentor2 phpDocumentor 2是一个可 ...

  7. eclipse中javadoc给项目生成api文档

    步骤 1.打开java代码,编写JavaDoc 注释,只有按照java的规范编写注释,才能很好的生成API文档,javadoc注释与普通注释的区别为多一个*(星号).普通代码注释为/*XXX*/,而j ...

  8. eclipse如何为java项目生成API文档、JavaDoc

    当我们的项目很大,编写了很多代码的时候,就需要生成一个标准的API文档,让后续的开发人员,或者合作者可以清晰的了解您方法的使用,那么如何将自己的项目生成API文档呢? 1.点击eclipse的[Pro ...

  9. eclipse如何为java项目生成API文档

    文章转载自: https://www.cnblogs.com/wdh1995/p/7705494.html 当我们的项目很大,编写了很多代码的时候,就需要生成一个标准的API文档,让后续的开发人员,或 ...

随机推荐

  1. 微信小程序-06-详解介绍.js 逻辑层文件-注册页面

    上一篇介绍的是 app.js 逻辑层文件中注册程序,对应的每个分页面都会有的 js 文件中 page() 函数注册页面 微信小程序-06-详解介绍.js 逻辑层文件-注册页面 宝典官方文档: http ...

  2. python第二十二天-----在做作业当中............

    作业 1, ATM:模拟实现一个ATM + 购物商城程序 额度 自定义实现购物商城,买东西加入 购物车,调用信用卡接口结账可以提现,手续费5%支持多账户登录支持账户间转账记录每月日常消费流水提供还款接 ...

  3. webApi core2 DI通过代码来获取容器里面已注入的对象

    请求服务 来自 HttpContext 的一次 ASP.NET 请求中可用的服务通过 RequestServices 集合公开的. 请求服务将你配置的服务和请求描述为应用程序的一部分.当你的对象指定依 ...

  4. MySQL5.7中的sql_mode默认值

    简介 在正常项目开发过程中,如果MySQL版本从5.6升级到5.7版本.作为DBA在考虑数据库版本升级带来的影响时,一般会有几个注意点: sql_mode 默认值的改变 optimizer_switc ...

  5. SSD 下的 MySQL(5.5) IO 优化

    一 目录 一 目录 二 背景 三 SSD 特性 四 基于 SSD 的数据库优化 五 A 项目 MySQL 主从关系图 六 程序切换之前调优 6.1 修改系统 IO 调度算法 6.2 修改 innodb ...

  6. Windows端部署zabbix-agent

    一.windows客户端的配置关闭windows防火墙或者开通10050和10051端口(1).关闭防火墙(不推荐直接关闭,测试可以这样做,尤其是最近勒索病毒猛烈)开始—控制面板—windows防火墙 ...

  7. popen()/pclose()阻塞性问题验证

    背景: popen()函数通过创建一个管道,调用fork()产生一个子进程,执行一个shell以运行命令来开启一个进程.这个管道必须由pclose()函数关闭,而不是fclose()函数. pclos ...

  8. January 14th, 2018 Week 02nd Sunday

    Embrace your life, for we only live once. 拥抱你的生活,因为我们只能活一次. We just live once, so I would rather liv ...

  9. January 03rd, 2018 Week 01st Wednesday

    My existence is not without reason. I know that I could be a quite a different person. 我的存在必定有意义,我知道 ...

  10. nginx与location语法详解

    Location语法优先级排列 匹配符 匹配规则 优先级 = 精确匹配 ^~ 以某个字符串开头 ~ 区分大小写的正则匹配 ~* 不区分大小写的正则匹配 !~ 区分大小写不匹配的正则 !~* 不区分大小 ...