Ant: Exclude Packageset Sub-Directory of Same Name as Another Packageset

Question

I am trying to run a javadoc task in Apache Ant that documents packages from two separate directories: src & tests. I want to document everything under src & only the utilities sub-directory under tests. The problem is that both directories contain a sub-directory named games. By including the games directory from src it also forces the games directory to be included from tests.

Neither of the following work:

<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>

<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>

I have also tried the following, but tests/games is always forced to be included if src/games is.

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

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

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

If I use a sourcepath for src & don't include "games.*" in packagenames, then the tests/games directory is omitted. But then I don't get any documentation for src/games.

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

I also tried using a nested fileset, but then there is a messages that all the files under the tests directory are skipped because the task wants a list of directories as input: Skipping <filename>.java since it is no directory

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

Is there any way around this so I can get documentation for both src/games & tests/utilities without tests/games? I have found many answers on excluding package directories. But nothing about when two package directories share the same name.

https://ant.apache.org/manual/Tasks/javadoc.html states that:

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

But this doesn't seem to be the case if another packageset or sourcepath is using the package name.

Java & Ant info:

$ 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

Answer 1

I was incorrect in thinking the task required a list of directories as input. By using the sourcepath & packageset tags it was looking for directories/packages. The answer was to use fileset instead.

  <javadoc
...
    <fileset dir="src/" includes="**/*.java"/>
    <fileset dir="tests/" includes="**/*.java" excludes="games/**"/>

This in turn required that I also add the src & tests directories to the classpath.

    <classpath>
      <pathelement path="src/"/>
      <pathelement path="tests/"/>
    </classpath>