Apache Ant javadoc任务：如何仅包含src全量与tests/utilities并排除同名tests/games

问题背景 #

需要通过Ant的javadoc任务为src和tests两个目录生成文档，具体需求：

• 生成src目录下所有内容的文档（包含src/games）
• 仅生成tests/utilities子目录的文档，排除tests/games

核心问题：只要配置中包含src/games，tests/games就会被强制纳入文档生成范围，多种配置尝试均无法解决该冲突。

已尝试的无效配置 #

以下是试过但未能解决问题的配置示例：

配置1：使用两个<packageset> #

<target name="docs">
  <javadoc
      defaultexcludes="yes"
      destdir="docs/"
      author="true"
      encoding="UTF-8"
      version="true"
      use="true"
      failonerror="yes"
      additionalparam="-Xdoclint:-html">
    <packageset dir="src/"/>
    <packageset dir="tests/" includes="utilities/"/>
  </javadoc>
</target>

配置2：指定packagenames和sourcepath #

<target name="docs">
  <javadoc packagenames="games.*"
      defaultexcludes="yes"
      destdir="docs/"
      author="true"
      encoding="UTF-8"
      version="true"
      use="true"
      failonerror="yes"
      additionalparam="-Xdoclint:-html">
    <sourcepath path="src/"/>
    <packageset dir="tests/" includes="utilities/"/>
  </javadoc>
</target>

其他无效配置片段 #

• 给tests的packageset添加excludes：

<javadoc packagenames="games.*"
...
    <sourcepath path="src/"/>
    <packageset dir="tests/" includes="utilities/" excludes="games/"/>

• 同时指定games.*,utilities.*包名，并用dirset排除tests/games：

<javadoc packagenames="games.*,utilities.*"
...
    <sourcepath path="src/"/>
    <sourcepath>
      <dirset dir="tests/" excludes="games/"/>
    </sourcepath>

• 使用patternset限定tests的packageset：

<javadoc packagenames="games.*"
...
    <sourcepath path="src/"/>
    <packageset dir="tests/">
      <patternset includes="utilities/"/>
    </packageset>

• 不包含games.*时能排除tests/games，但无法生成src/games：

<javadoc packagenames="foobar"
...
    <sourcepath path="src/"/>
    <packageset dir="tests/" includes="utilities/"/>

• 使用fileset时出现文件被跳过的错误：

<sourcepath>
  <fileset dir="tests/">
    <exclude name="games/**/*.java"/>
  </fileset>
</sourcepath>

错误提示：Skipping <filename>.java since it is no directory

官方文档说明 #

Apache Ant官方文档提到：

The packagenames, excludepackagenames and defaultexcludes attributes of the task have no effect on the nested <packageset> elements.

但实际使用中，当结合其他packageset或sourcepath使用包名时，该规则似乎不生效。

环境版本 #

$ java -version
openjdk version "17.0.5" 2022-10-18
OpenJDK Runtime Environment (build 17.0.5+8-Ubuntu-2ubuntu122.04)
OpenJDK 64-Bit Server VM (build 17.0.5+8-Ubuntu-2ubuntu122.04, mixed mode, sharing)

$ ant -version
Apache Ant(TM) version 1.10.12 compiled on January 17 1970

解决方案 #

要实现仅生成src/games和tests/utilities的文档、排除tests/games，可以通过以下两种方式解决：

方案1：拆分javadoc任务并合并输出 #

将src和tests的文档生成分开执行，指定不同的源路径和规则，最后合并到同一输出目录：

<target name="docs" depends="docs-src, docs-tests"/>

<target name="docs-src">
  <javadoc
      defaultexcludes="yes"
      destdir="docs/"
      author="true"
      encoding="UTF-8"
      version="true"
      use="true"
      failonerror="yes"
      additionalparam="-Xdoclint:-html">
    <packageset dir="src/"/>
  </javadoc>
</target>

<target name="docs-tests">
  <javadoc
      defaultexcludes="yes"
      destdir="docs/"
      author="true"
      encoding="UTF-8"
      version="true"
      use="true"
      failonerror="yes"
      additionalparam="-Xdoclint:-html"
      merge="yes"> <!-- 合并到已有的docs目录 -->
    <packageset dir="tests/" includes="utilities/"/>
  </javadoc>
</target>

关键是使用merge="yes"参数，让第二个javadoc任务将内容合并到第一个任务生成的文档目录中，既避免包名冲突导致tests/games被包含，又能得到完整的文档。

方案2：使用fileset精确指定文件 #

直接基于文件路径筛选，绕开包名匹配逻辑，从根源上避免同名包冲突：

<target name="docs">
  <javadoc
      defaultexcludes="yes"
      destdir="docs/"
      author="true"
      encoding="UTF-8"
      version="true"
      use="true"
      failonerror="yes"
      additionalparam="-Xdoclint:-html">
    <!-- 包含src下所有java文件 -->
    <fileset dir="src/" includes="**/*.java"/>
    <!-- 包含tests/utilities下的java文件，排除tests/games -->
    <fileset dir="tests/" includes="utilities/**/*.java" excludes="games/**/*.java"/>
  </javadoc>
</target>

内容的提问来源于stack exchange，提问作者AntumDeluge