Bug 47790 - javadoc: don't create packagenames option if filesets are used
javadoc: don't create packagenames option if filesets are used
Status: NEW
Product: Ant
Classification: Unclassified
Component: Core tasks
1.7.1
PC Linux
: P2 blocker with 1 vote (vote)
: ---
Assigned To: Ant Notifications List
:
Depends on:
Blocks:
  Show dependency tree
 
Reported: 2009-09-05 21:24 UTC by Jens Elkner
Modified: 2010-01-16 00:32 UTC (History)
2 users (show)



Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Jens Elkner 2009-09-05 21:24:13 UTC
If javadoc gets called with packagenames as well as sourcenames option, all
classes are listed twice in the allclasses-frame.html page. E.g.:

javadoc -d build/docs/api \
  -classpath /local/apps/javax/slf4j/slf4j-api.jar \
  -sourcepath src \
  de.ovgu.cs.wizard \
  `find src -name "*.java" | xargs`

However, omitting packagenames or sourcenames option works. E.g.:

javadoc -d build/docs/api \
  -classpath /local/apps/javax/slf4j/slf4j-api.jar \
  -sourcepath src \
  `find src -name "*.java" | xargs`

javadoc -d build/docs/api \
  -classpath /local/apps/javax/slf4j/slf4j-api.jar \
  -sourcepath src \
  de.ovgu.cs.wizard

Since ant generates the packagenames option automatically, one can't use the
filesets anymore or gets a corrupted  allclasses-frame.html. E.g.:

<javadoc destdir="${build.docs.dir}/api"
    author="true" version="true" use="true"
    additionalparam="-breakiterator"
    doctitle="${doctitle}" windowtitle="${windowtitle}"
    header="${header}"
    bottom="${bottom}"
    sourcepath="${src.dir}"
    maxmemory="512m"
>
    <classpath>
        <path refid="classpath.base"/>
    </classpath>
    <fileset dir="${src.dir}/${codebase}" excludes="**/res/**, **/*.dtd,
        **/test/*.java,**/Test*, **/*.form,@{excludes}"/>
    <link href="${jdkAPI}" />
</javadoc>

produces such a bogus allclasses-frame.html
Comment 1 Stefan Bodewig 2009-09-08 07:52:46 UTC
see also bug #47196 and the updated documentation in svn 0

sourcepath isn't directly equivalent to -sourcepath, it does more.  In fact it implicitly creates nested packagesets for each directory using the packagenames attribute - or "*" if no packagenames have been specified.

In your case this leads to the bogus all-classes frame - if you don't specify a sourcepath attribute at all, it should work.
Comment 2 Stefan Bodewig 2009-09-14 03:07:37 UTC
is "don't specify the sourcepath attribute at all" good enough to close this?

The implementation won't change, we might tweak the documentation, though.
Comment 3 Jens Elkner 2009-09-14 09:01:29 UTC
Well, for my puposes it would be ok for now.

However, having a pkgnames attribute is IMHO the cleaner way to handle special needs and get closer to the javadoc tool. I.e. if pkgnames is set (even if empty), the ant task should not generate pkgnames, otherwise behave in the traditional way.
Comment 4 Robert Simpson 2009-11-28 16:53:37 UTC
I ran into this issue while attempting to create a javadoc task equivalent to the following javadoc command which generates a couple hundred documentation files (http://code.google.com/p/filewise/source/browse/#svn/trunk/docs/api):

javadoc -private -sourcepath /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/src -source 1.6 -J-Xmx128m -d docs/api src/com/filewise/*.java src/com/applcore/java/*/*.java

As indicated, the following seemingly equivalent task definition "does more" in that it generates several thousand output files including doc for all of the JDK source files (requiring the memory to be increased to -Xmx768m), which takes about 25 minutes:

<property name="sdk.java.src"  location="/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/src"/>
<!-- that property is actually set differently with <whichresource> depending on whether we're on Mac, Linux or Windows -->

<target name="doc" depends="init">
   <javadoc access="protected" destdir="docs/api" source="1.6" maxmemory="768m">
      <packageset dir="src"/>
      <sourcepath>
         <pathelement location="${sdk.java.src}"/>
      </sourcepath>
   </javadoc>
</target>

I tried the "don't specify the sourcepath attribute at all" solution, but then it no longer picks up the inherited comments from the JDK, which makes sense, since there's no longer anything to indicate where the JDK source files are.  Thus all of the "Description copied from ..." comments disappeared from the output files.
 
I tried adding "-sourcepath" as an additionalparam, but strangely it thought there was more than one "-sourcepath", until I replaced "<packageset>" with "<fileset>".  So the final workaround for properly specifying the "-sourcepath" parameter appears to be:

<target name="doc" depends="init">
   <javadoc access="protected" destdir="docs/api" source="1.6" maxmemory="768m" additionalparam="-sourcepath ${sdk.java.src}">
      <fileset dir="src">
         <include name="*.java"/>
         <include name="**/*.java"/>
      </fileset>
   </javadoc>
</target>

It now generates only 250 files and runs in as little as 128m, or with more memory takes 25 seconds rather than 25 minutes.

Rob S. http://Lnkd.com?24
Comment 5 Robert Simpson 2009-11-28 17:27:36 UTC
Bug #41292 was a better place to put that.