Bug 41292 - javadoc task: sourcepath for JDK sources broken
Summary: javadoc task: sourcepath for JDK sources broken
Status: NEW
Alias: None
Product: Ant
Classification: Unclassified
Component: Core (show other bugs)
Version: 1.7.0
Hardware: Other Windows 2000
: P2 normal with 1 vote (vote)
Target Milestone: ---
Assignee: Ant Notifications List
Depends on:
Reported: 2007-01-04 13:28 UTC by Andr
Modified: 2018-09-11 15:36 UTC (History)
0 users


Note You need to log in before you can comment on or make changes to this bug.
Description Andr 2007-01-04 13:28:45 UTC
With the <javadoc> task I use a nested <packageset> element for my own project
packages and a the "sourcepath" attribute to link the JDK sources for to get
some descendant comments via {@inheritDoc}, like so:

class Foo extends JComponent {
   * {@inheritDoc}<p/>
   * My additional comments ...
  public someJComponentMethod() {

My task looks like the following example:

  destdir="${destdir}"              // my output dir
  sourcepath="${sourcepath}"        // the *unzipped* JDK sources
  classpathref="${classpathref}"    // additional, external libraries.

  <packageset dir="${src}"          // my sources dir
              includes="${pkg}/**"  // my project package

That way it works with Ant 1.6.*.

With Ant 1.7.0 (and Java 6 std. doclet), the entire JDK sources are loaded for
being documented!

task output:

Loading source files for package {my package}...
Loading source files for package {*all* JDK sources}...

I played a bit around with a combined <classpath> nested element and with
<excludepackage> and the like, but can't find a solution.

A bug (?) or is there another (new?) way to get the desired behaviour?
Comment 1 Stefan Bodewig 2009-09-08 08:00:04 UTC
sourcepath does more than you think 8and yes, this has been added in 1.7.x).

see also bug #47196 or bug #47790 and the updated documentation in svn revision 786510

Unfortunately I'm not familar enough with the Java6 standard doclet to know what it really needs for @inheritdocs to work.  Maybe excludepackagenames="*" would work in combination with your sourcepath attribute.
Comment 2 Robert Simpson 2009-11-28 17:18:49 UTC
>> is there another (new?) way to get the desired behaviour?

I finally managed to invent a workaround for getting the {@inheritDoc} (explicit or implied) to work with Ant. (I had updated bug #47790 before I saw this one)

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

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

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

<property name="sdk.java.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"
      <packageset dir="src"/>
         <pathelement location="${sdk.java.src}"/>

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

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