Javadoc：为文件夹和子文件夹中的文件生成文档

Javadoc 是 Java 的一项功能，可以从源代码中提取文档注释并生成 HTML 文档。在 Java 中使用 Javadoc 生成文档非常方便，只需使用 javadoc 命令并指定要生成文档的 Java 源文件即可。

但是如果你有大量的 Java 源代码文件，以及多层嵌套的子文件夹，手动编写 javadoc 命令行可能非常繁琐。在这种情况下，你可以使用一些工具来自动生成 javadoc 命令行，以便快速生成文档。

使用 Javadoc 生成文档的方式

Javadoc 命令用法：

javadoc [options] [packagenames] [sourcefiles] [@files]

其中，options 指定了一些参数，packagenames 指定要包含在文档中的包名称，sourcefiles 指定要包含在文档中的 Java 源代码文件，@files 指定一个文件，其中包含其他文件名和选项，这些选项将传递给 Javadoc 工具。

使用 Javadoc 命令生成文档的基本步骤如下：

1. 编写 Java 源代码文件并添加文档注释。
2. 使用 javadoc 命令生成文档。

文档注释需要使用特定格式，以便 Javadoc 工具可以正确解析它们。通常，文档注释位于类、接口、字段、方法等声明之前，并以 /** 开始、以 */ 结束。

下面是一个示例：

/**
 * This is a simple class that represents a book.
 */
public class Book {
    /**
     * The title of the book.
     */
    public String title;
    /**
     * The author of the book.
     */
    public String author;
    /**
     * The year the book was published.
     */
    public int year;
    /**
     * Constructs a book object.
     * @param title the title of the book.
     * @param author the author of the book.
     * @param year the year the book was published.
     */
    public Book(String title, String author, int year) {
        this.title = title;
        this.author = author;
        this.year = year;
    }
}

可以看到，该类的文档注释包含了该类的简单描述以及两个字段和一个构造函数的说明。在注释中使用 @param 标记指定方法参数。

使用自动化工具批量生成文档

如果你有许多 Java 源代码文件，可能会很麻烦手动编写 javadoc 命令行。在这种情况下，你可以使用一些自动化工具来批处理生成文档。

Ant

Ant 是一个基于 Java 的构建工具，可以用于自动化构建、测试和部署软件。Ant 提供一个名为 javadoc 的任务，用于生成文档。

以下是一个示例 Ant 构建文件 (build.xml)，它会在 src 目录下查找所有 Java 源代码文件并生成文档：

<project name="MyProject" default="javadoc">
  <target name="javadoc">
    <javadoc packagenames="com.mycompany.mypackage">
      <fileset dir="src" includes="**/*.java" />
    </javadoc>
  </target>
</project>

在该文件中，javadoc 任务使用 <fileset> 元素指定要包含在文档中的 Java 源代码文件。在 packagenames 属性中指定了包名称。

使用该构建文件可以生成文档：

ant javadoc

Maven

Maven 是另一个 Java 构建工具，它使用 XML 配置文件来自动化构建、测试和部署软件。Maven 也提供一个名为 javadoc 的插件，用于生成文档。

以下是一个 Maven 配置文件 (pom.xml)，它会在 src/main/java 目录下查找所有 Java 源代码文件并生成文档：

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
          <execution>
            <goals>
              <goal>javadoc</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <sourcepath>src/main/java</sourcepath>
          <subpackages>com.mycompany.mypackage</subpackages>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

在该文件中，maven-javadoc-plugin 插件使用 <sourcepath> 元素指定 Java 源代码文件所在的目录。在 <subpackages> 元素中指定要包含在文档中的包名称。

使用该配置文件可以生成文档：

mvn javadoc:javadoc

Gradle

Gradle 是另一个流行的 Java 构建工具，它使用 Groovy 或 Kotlin 脚本来自动化构建、测试和部署软件。Gradle 提供了一个名为 javadoc 的任务，用于生成文档。

以下是一个 Gradle 构建文件 (build.gradle.kts)，它会在 src/main/java 目录下查找所有 Java 源代码文件并生成文档：

plugins {
    java
}

tasks.javadoc {
    sourceSets.main.java.srcDirs("src/main/java")
    options.addStringOption("subpackages", "com.mycompany.mypackage")
}

在该文件中，javadoc 任务使用 sourceSets 属性指定 Java 源代码文件所在的目录。在 options 属性中指定要包含在文档中的包名称。

使用该构建文件可以生成文档：

gradle javadoc

结论

无论你使用哪种自动化工具，都应该能够轻松地为文件夹和子文件夹中的 Java 源代码文件批量生成 Javadoc 文档。这使得文档编写更加高效，并使文档更容易维护。