技术开发 频道

Java开发必备小助手:Javadoc文档注释

  假设我们的源代码为:

package doublelife;

  
/**

  
* Description:

  
*

  Copyright(C),
2011-2012

  
*

  
Date: 2012/1/4

  
* @author DoubleLife

  
* @version 1.0

  
*/

  publicclass TestJavaDoc {

  
/**

  
* Property:name

  
*/

  
private String name;

  
/**

  
* Setter Method

  
* @return name

  
*/

  
public String getName() {

  returnname;

  }

  
/**

  
* Getter Method

  
* @param name

  
*/

  publicvoid setName(
String name) {

  this.name
= name;

  }

  }

 

  运行javadoc.exe以后,输出为:

  •   Loading source files for package doublelife...
  •   Constructing Javadoc information...
  •   Standard Doclet version 1.4.2_19
  •   Generating C:\JavaDoc\doc\constant-values.html...
  •   Building tree for all the packages and classes...
  •   Generating C:\JavaDoc\doc\doublelife\class-use\TestJavaDoc.html...
  •   Generating C:\JavaDoc\doc\doublelife\package-use.html...
  •   Building index for all the packages and classes...
  •   Generating C:\JavaDoc\doc\overview-tree.html...
  •   Generating C:\JavaDoc\doc\index-files\index-1.html...
  •   Generating C:\JavaDoc\doc\index-files\index-2.html...
  •   Generating C:\JavaDoc\doc\index-files\index-3.html...
  •   Generating C:\JavaDoc\doc\index-files\index-4.html...
  •   Generating C:\JavaDoc\doc\deprecated-list.html...
  •   Building index for all classes...
  •   Generating C:\JavaDoc\doc\allclasses-frame.html...
  •   Generating C:\JavaDoc\doc\allclasses-noframe.html...
  •   Generating C:\JavaDoc\doc\index.html...
  •   Generating C:\JavaDoc\doc\packages.html...
  •   Generating C:\JavaDoc\doc\doublelife\package-frame.html...
  •   Generating C:\JavaDoc\doc\doublelife\package-summary.html...
  •   Generating C:\JavaDoc\doc\doublelife\package-tree.html...
  •   Generating C:\JavaDoc\doc\doublelife\TestJavaDoc.html...
  •   Generating C:\JavaDoc\doc\package-list...
  •   Generating C:\JavaDoc\doc\help-doc.html...
  •   Generating C:\JavaDoc\doc\stylesheet.css...

  生成的目录结构如下图。

为了代码的可读性,今天你Javadoc了吗?

  点击index.html查看内容如下。左边的TestJavaDoc即为目标class文件名,右边Class Summary显示的是该类的一些信息,如描述,版权,生成日期等。

为了代码的可读性,今天你Javadoc了吗?

  点击TestJavaDoc可以查看相关的属性即方法说明。

  相关关键词说明

  JavaDoc支持HTML代码与标记@。上例中,实现了换行。如果您熟悉HTML语法,便很容易理解。关于@,如果我们希望javadoc工具生成更详细的文档信息,例如为方法参数、方法返回值等生成详细的说明信息,则可以利用javadoc标记,有如下标记:

  @author 作者名

  @version 版本标识

  @parameter 参数及其意义

  @since 最早使用该方法/类/接口的JDK版本

  @return 返回值

  @throws 异常类及抛出条件

  @deprecated 引起不推荐使用的警告

  @see reference

  @override 重写

  JavaDoc工具相关用法

  javadoc命令可对源文件、包来生成API文档,常用选项有如下几个:

  javadoc [选项] [软件包名称] [源文件] [@file]

  •   -overview <文件> 读取 HTML 文件的概述文档
  •   -public 仅显示公共类和成员
  •   -protected 显示受保护/公共类和成员(默认)
  •   -package 显示软件包/受保护/公共类和成员
  •   -private 显示所有类和成员
  •   -help 显示命令行选项并退出
  •   -doclet <类> 通过替代 doclet 生成输出
  •   -docletpath <路径> 指定查找 doclet 类文件的位置
  •   -sourcepath <路径列表> 指定查找源文件的位置
  •   -classpath <路径列表> 指定查找用户类文件的位置
  •   -exclude <软件包列表> 指定要排除的软件包的列表
  •   -subpackages <子软件包列表> 指定要递归装入的子软件包
  •   -breakiterator 使用 BreakIterator 计算第 1 句
  •   -bootclasspath <路径列表> 覆盖引导类加载器所装入的类文件的位置
  •   -source <版本> 提供与指定版本的源兼容性
  •   -extdirs <目录列表> 覆盖安装的扩展目录的位置
  •   -verbose 输出有关 Javadoc 正在执行的操作的消息
  •   -locale <名称> 要使用的语言环境,例如 en_US 或 en_US_WIN
  •   -encoding <名称> 源文件编码名称
  •   -quiet 不显示状态消息
  •   -J<标志> 直接将 <标志> 传递给运行时系统
0
相关文章