How can I make an Ant Javadoc class exclude two files?

Question

I am documenting some Java webservices and the supporting datatypes. There are two services that I do not want documented. What is the correct way to exclude a small number of files from the Ant javadoc task?

I have tried several iterations using files or filesets nested under sourcepath or sourcefiles with various combinations of include and exclude.

The base target I have defined correctly documents all of my webservices:

    <target name="javadoc.webservices" description="Generate the documentation for companyproject webservices">
    <delete dir="docs/webservices" failonerror="true"/>
    <mkdir dir="docs/webservices"/>
    <javadoc packagenames="com.company.project.webservices,com.company.project.models.*"
             defaultexcludes="yes"
             destdir="docs/webservices"
             author="true"
             version="true"
             use="true"
             windowtitle="company project Webservices">
        <doctitle><![CDATA[<h1>company project Webservices</h1>]]></doctitle>
        <bottom><![CDATA[<i>Copyright &#169; 2011 company Corp. All Rights Reserved.</i>]]></bottom>
        <sourcepath>
            <path location="companyproject-ejb/src/java"/>
            <path location="companyproject-models/src"/>
        </sourcepath>
        <classpath>
            <path refid="companyproject-models.module.classpath"/>
            <path refid="companyproject-ejb.module.classpath"/>
            <pathelement location="${companyproject-ejb.output.dir}"/>
        </classpath>
    </javadoc>
</target>

Some variations I have tried include:

<sourcefiles>
            <fileset dir="companyproject-ejb/src/java">
                <include name="**/*.java"/>
                <exclude name="**/*IntegrationTestWS*, **/*NhinInterfaceWS*"/>
            </fileset>
        </sourcefiles>

This errors with javadoc.exe CreateProcess error=87, The parameter is incorrect

<sourcepath>
            <fileset dir="companyproject-ejb/src/java">
                <include name="**/*.java"/>
                <exclude name="**/*IntegrationTestWS*, **/*NhinInterfaceWS*"/>
            </fileset>
        </sourcepath>

Same error as sourcefiles, but has a lot of messages saying skipping <somefile> since it is no directory.

I have tried similar variations using <files> instead of <fileset>.

I think I am missing some basic understanding of how includes/excludes works. Thank you for your help!

AlexR didn't quite get it but came close. I removed <sourcepath> and added

<fileset dir="./Companyproject-ejb/src/java/">
<include name="com/Company/project/webservices/*"/>
<exclude name="**/IntegrationTestWS*"/>
<exclude name="**/NhinInterfaceWS*"/>
</fileset>
<packageset dir="./Companyproject-models/src/">
    <include name="com/Company/project/models/**"/>
</packageset>

Having only a fileset led javadoc to complain that it couldn't find any packages. Packageset behaves like a dirset, so it can't exclude single files, only directories. In this case I was able to define a packageset for one set of doco and a fileset for the restricted set and get around it.

Answer 1

<fileset dir="src" defaultexcludes="yes">
  <include name="com/dummy/test/**"/>
  <exclude name="com/dummy/test/doc-files/**"/>
</fileset>

..................

I think that your mistake is the "sourcefiles" and "sourcepath" tags. Try to remove them. For more information take a look here: http://ant.apache.org/manual/Tasks/javadoc.html

Good luck!

Answer 2

Just had the same problem and digged a bit into man javadoc to come to the conclusion that there is no solution, except for the workaround that happened to work in the OPs case. Yet I would like to document what I read from the docs.

Ant's javadoc task is only a wrapper around Java's javadoc, so the latter's documentation applies. In particular, javadoc seems to have two cleanly separated concepts of generating documentation:

1. document packages
2. document individual classes

For (1) we specify package names like my.nice.package and -sourcepath to help javadoc find these packages. Using ant, the names can be provided either as packagenames or as packageset where the latter converts path names to package names (slash to dot).

For (2) we specify file paths, possibly with wildcards. Then each individual file is documented. With ant, this is done via a nested fileset, which allows us to exclude files.

Now it seems that two things don't play well together in javadoc.

a) When documenting packages, there is no means to exclude individual files.

b) When documenting individual files, the packages are not documented, which leads to error messages about wrong references to package names when using {@link my.package}.

Search for Documenting Both Packages and Classes in man javadoc, to see where I read this fror.

This is a decade old problem, it seems :-(