javaDOC

 

javadoc - Java API 文档生成器

http://www.computersci.net/articles/jdk1.2/docs/tooldocs/win32/javadoc.html

简单示例

可以对整个包或单个类运行 javadoc。每个包名有一个相应的目录名。在下面的示例中，源文件位于 C:\home\src\java\awt\*java。目的目录是 C:\home\html。

建立包的文档

要建立包的文档，该包的源文件（*.java）必须位于一个与该包名字相同的目录中。如果包名由几个标识符组成（用点号分隔），则每个标识符代表一个不同的目录。因而，所有java.awt 类必须位于名为 java\awt\ 的目录中。可用如下两种方式之一运行 javadoc -- 通过改变目录（用 cd）或使用 sourcepath 选项。不能使用通配符指定多个包。

• 情况 1- 换到包目录 - 换到全限定包的父目录。然后运行 run javadoc，并提供想要建立其文档的一个或多个包的名字：

    C:> cd C:\home\src\
    C:> javadoc -d C:\home\html java.awt java.awt.event
  

• 情况 2 - 从任何目录 - 在这种情况下，当前目录是什么没有关系。运行 javadoc 时用 sourcepath 提供全限定包的父目录，并提供想要建立其文档的一个或多个包的名字：

    C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event
  

这两种情况都将产生包 java.awt 和 java.awt.event 中公共和保护类和接口的 HTML 格式文档，并将 HTML 文件保存在指定目的目录（C:\home\html）中。因为要生成两个或多个包，所以文档具有三个框架 -- 包列表、类列表和主页。

建立类的文档

要建立一个或多个源文件（.java）的文档，这些文件不必位于特定目录中。可以用如下两种方式之一运行 javadoc -- 通过改变目录（用 cd）或完全指定 .java 文件的路径。选项 -sourcepath 在建立源文件的文档时没有作用。可使用命令行通配符，例如星号（*），指定多个类。

• 情况 1 - 换到源目录 - 换到保存 .java 文件的目录。然后运行 javadoc，并提供想要建立其文档的一个或多个源文件名。

    C:> cd C:\home\src\java\awt
    C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java
  

  该示例产生类 Button、Canvas 和以 Graphics 开头的类的 HTML 格式文档。因为是源文件而不是包名作为参数传递给 javadoc，所以文档具有两个框架 -- 类列表和主页。

• 情况 2 - 改变到包的根目录 - 当要为相同根目录下不同子包中的单个源文件建立文档时，这是非常有用的。改变到包的根目录，并提供源文件相对于其根的路径。

    C:> cd /home/src/
    C:> javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
  

  该示例产生类 Button 和 Applet 的 HTML 格式文档。

• 情况 3 - 从任何目录 - 在这种情况下，当前目录是什么没有关系。运行 javadoc，并提供想要建立其文档的 .java 文件的绝对路径（或相对于当前目录的相对路径）。

    C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.java
  

  该示例产生类 Button 和以 Graphics 开头的类的 HTML 格式文档。

建立包和类的文档

可同时建立整个包和单个类的文档。下面是一个混合前两个示例的示例。可使用 -sourcepath 指定包的路径但不作为单个类的路径。

  C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\home\src\java\applet\Applet.java

该示例生成包 java.awt 和类 Applet 的 HTML 格式文档（Javadoc 从 Applet.java 源文件中的包声明（如果有）中确定 Applet 的包名）。

实际示例

Javadoc 有许多有用的选项，有些相对其他更为常用。下面是实际中我们用来在 Java 平台 API 上运行 javadoc 的命令，它使用了 makefile 变量（除了未列出所有要建文档的包之外）。

javadoc -sourcepath /jdk/src/share/classes \   /* 源文件路径        */
        -d /jdk/build/api                  \   /* 目的目录          */
        -use                               \   /* 添加“用法”文件  */
        -splitIndex                        \   /* 分割索引 A-Z      */
        -windowtitle $(WINDOWTITLE)        \   /* 添加窗口标题      */
        -doctitle $(DOCTITLE)              \   /* 添加文档标题      */
        -header $(HEADER)                  \   /* 添加运行页眉文本  */
        -bottom $(BOTTOM)                  \   /* 添加底部文本      */
        -group $(GROUPCORE)                \   /* 概述页的核心标题  */
        -group $(GROUPEXT)                 \   /* 概述页的扩展标题  */
        -overview overview-core.html       \   /* 概述文本          */
        -J-Xmx180m                         \   /* 180MB 内存        */
        java.lang java.lang.reflect        \   /* 要建立其文档的包  */
        java.util java.io java.net         \
        java.applet

WINDOWTITLE = 'Java 平台 1.2 最终 API 规范'
DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> Platform 1.2 Final API Specification'
HEADER = '<b>Java Platform 1.2</b><br><font size="-1">Final</font>'
BOTTOM = '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi"> 提交
    bug 或功能 </a><br><br>Java 是 Sun Microsystems , Inc 在美国和其他国家
    的商标或注册商标。<br>Copyright 1993-1998
    Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A.
    保留所有权利。</font>'
GROUPCORE = '"核心包" "java.*:com.sun.java.*:org.omg.*"
GROUPEXT  = '"扩展包" "javax.*"'

如果省略 -windowtitle 选项，则 javadoc 将文档标题复制到窗口标题。-windowtitle 选项是没有必要的，除非文档标题包含 HTML 标记。

如果像这里所做的一样省略 -footer 选项，则 javadoc 将页眉文本复制到脚注文本。

其他重要的选项是 -classpath 和 -link。

 

Code Conventions for the JavaTM Programming Language

 

http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html