《Thinking in Java》读书笔记（二）——Javadoc

Javadoc怎么用？

（中文书P33英文书P82有概念的简单介绍）

 

Javadoc 解析 Java 源文件中的声明和文档注释，并产生相应的 HTML 页（缺省），描述公有类、保护类、内部类、接口、构造函数、方法和域。

可对 整个包、单个源文件 或 二者 运行 Javadoc。在第一种情况中，将一系列包名作为参数传递给 javadoc。在第二种情况中，传递一系列源（.java）文件名。

在实现时，Javadoc 要求且依赖于 java 编译器完成其工作。Javadoc 调用部分 javac 编译声明部分，忽略成员实现。它建立类的内容丰富的内部表示，包括类层次和“使用”关系，然后从中生成 HTML。Javadoc 还从源代码的文档注释中获得用户提供的文档。

实际上，Javadoc 将在不带方法体的纯 stub 文件的 .java 源文件上运行。这意味着可以在创建 API 的最早期阶段，在编写任何代码之前，就可编写文档注释并运行 Javadoc。

完全对应于实际的实现，这些实现可能有赖于隐式的（而非显式的）源代码。例如，Javadoc 将建立在 .class 文件中存在但在源代码中不存在的缺省构造函数的文档。

当 Javadoc 建立其内部文档结构时，它将加载所有引用的类。由于这一点，Javadoc 必须能查找到所有引用的类，包括引导类、扩展类和用户类。一般而言，所创建的类必须加载为扩展或位于 Javadoc 的类路径中。

 

下面看个示例来认识如何使用Javadoc。

 

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

建立包的文档

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

• 情况 1- 改变包目录 - 改变全限定包的父目录。然后运行 run javadoc，并提供想要建立其文档的一个或多个包的名字：
•   % cd /home/src/
•   % javadoc -d /home/html java.awt java.awt.event
• 情况 2 - 从任何目录 - 在这种情况下，当前目录是什么没有关系。运行 javadoc 时用 sourcepath 提供全限定包的父目录，并提供想要建立其文档的一个或多个包的名字：
•   % javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event

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

建立类的文档

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

• 情况 1 - 换到源目录 - 换到保存 .java 文件的目录。然后运行 javadoc，并提供想要建立其文档的一个或多个源文件名。
•   % cd /home/src/java/awt
•   % javadoc -d /home/html Button.java Canvas.java Graphics*.java

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

• 情况 2 - 改变到包的根目录 - 当要为相同根目录下不同子包中的单个源文件建立文档时，这是非常有用的。改变到包的根目录，并提供源文件相对于其根的路径。
•   % cd /home/src/
•   % javadoc -d /home/html java/awt/Button.java java/applet/Applet.java

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

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

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

建立包和类的文档

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

  % javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java

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

 

资料来源：http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html

 

虽然资料说得很详细，但是没有亲手写过，还是挺模糊的。这部分书是放假在家时看的，没得做练习，现在回到学校，要把课后的练习做一遍才行。只是又到开学，时间得用挤的了。