And here is the fix ;-)

    <target name="-javadoc-build" depends="init">
        <mkdir dir="${dist.javadoc.dir}"/>
        <javadoc destdir="${dist.javadoc.dir}" 
                 source="${javac.source}" 
                 notree="${javadoc.notree}" 
                 use="${javadoc.use}" 
                 nonavbar="${javadoc.nonavbar}" 
                 noindex="${javadoc.noindex}" 
                 splitindex="${javadoc.splitindex}" 
                 author="${javadoc.author}" 
                 version="${javadoc.version}" 
                 windowtitle="${javadoc.windowtitle}" 
                 private="${javadoc.private}" 
                 failonerror="true"
                 useexternalfile="yes">
            <classpath>
                <path path="${javac.classpath}"/>
            </classpath>
            <sourcepath>
                <pathelement location="${src.dir}"/>
            </sourcepath>
            <fileset dir="${src.dir}"/>
        </javadoc>
    </target>

The task needs the option useexternalfile="yes" to prevent large
command line arguments.

Ant documentation from
http://ant.apache.org/manual/CoreTasks/javadoc.html:

useexternalfile (1.2+)

indicates whether the sourcefile name specified in srcfiles or as
nested source elements should be written to a temporary file to make
the command line shorter. Also applies to the package names specified
via the packagenames attribute or nested package elements. (yes | no).
Default is no.


regards,
  josh.

Moving to "projects" category for evaluation

Thanks for the fix. I will apply it for 4.1.

Does useexternalfile="yes" handle also the long classpath? (Docs do
not mention that, if so - Ant doc bug?) You (reporter) specifically
tested this change and it fixes the problem in your case?

IMHO the "useexternalfile" invokes the javadoc with:

javadoc @argfile

and @argfile ist the temporary external file.

Here is the documantation from sun:

http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#argumentfiles

"To shorten or simplify the javadoc command line, you can specify one
or more files that themselves contain arguments to the javadoc command
(except -J options). This enables you to create javadoc commands of
any length on any operating system." 
[...]
"Example - Single Arg File
You could use a single argument file named "argfile" to hold all
Javadoc arguments:
  C:> javadoc @argfile"

And yes, my very (very) long classpath works with the option
"useexternalfile". IMHO it's a ant doc bug.

Ok, a closer look to the ant source
(http://cvs.apache.org/viewcvs.cgi/ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java?rev=1.124.2.5&view=markup)

 /**
  * Write sourcefiles and package names to a temporary file
  * if requested.
  */
  if (useExternalFile) {
    if (tmpList == null) {
      tmpList = fileUtils.createTempFile("javadoc", "", null);
      tmpList.deleteOnExit();
      toExecute.createArgument()
        .setValue("@" + tmpList.getAbsolutePath());
    }
    srcListWriter = new PrintWriter(
      new FileWriter(tmpList.getAbsolutePath(), true));
  }

useexternalfile definitely use the @external file. It's a ant-doc-bug.
And the option works fine for the netbeans build file.

regards,
  josh.

I've added some comments to
http://issues.apache.org/bugzilla/show_bug.cgi?id=30410

I just wanted to fix this but I discovered different problem which is
filed as <http://issues.apache.org/bugzilla/show_bug.cgi?id=27814> in
Ant issuezilla. Till it is fixed I will not implement this issue
because it breaks Javadoc generation completely on my WinXP.

I'm curious how it can work for you Aljoscha?

The problem is really in JDK's javadoc executable and I'm going to
file bug against it and will attach it both here in in Ant's issue.

JDK issue: <http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6202474>

Is it really a bug in the JDK that it interprets \ inside a string
like the Java language does? IMHO just absent documentation. Perhaps
Ant should be doubling \ in this situation?

Yes, perhaps it is just lack of documentation and patch in Ant
issuezilla suggests exactly that solution. On the other hand it seems
to me strange to force me on Win platform to escape all backslashes in
my arguments file just because Java language does that. And btw.
StreamTokenizer (which is used to read the arguments file) interpret
backslash as escape *only* when inside quot. So if your path do not
contain spaces then you do not have to quot it and in that case you do
not have to escape all backslashes.

FYI - Ant #27814 fixed in Ant dev trunk.

Can take advantage of fix in Ant. Should be available in 1.6.5.

*** This issue has been marked as a duplicate of 57375 ***