[PATCH] Various fixes to javadoc generation

[Jan Hlavatý <hl...@code.cz>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I've been playing around with javadoc building a little more.
Attached patch contains results:

- - made some dependency fixes so that javadoc can be built right from
clean state

- - added -source 1.4 to javadoc invocations to prevent JDK 1.5 javadoc
from complaining about enums. These enums must go though!

- - replaced nasty javadoc hack in "javadocsubpackages" target with
regular javadoc tag that does exactly the same thing (original author
probably didn't fugure out how to pass JVM parameter to increase memory
~ to javadoc tag)

I can generate whole documentation now, including grammars.
I even found a bug in JDK 1.5 javadoc during the process, which i
reported promptly ;-)

Javadoc tags are (as usual) a real mess, I'd like to fix them, but
without having commit access it would be really painful ;-)

I also looked at future JDK 1.5 compatibility, there are a lot of enum
identifiers that have to be changed ;)

Don't forget to apply my prevoius javadoctools.dir fix ;-)

Jan

- ----------
Index: build.xml
===================================================================
- --- build.xml	(revision 37084)
+++ build.xml	(working copy)
@@ -350,7 +350,7 @@
~ <!--                           Javadoc targets
~  -->
~ <!--
=================================================================== -->

- -  <target name="javadoc"
depends="publishedapi,derbydocs,toolsdocs,grammardocs"/>
+  <target name="javadoc"
depends="buildsource,publishedapi,derbydocs,toolsdocs,grammardocs"/>

~   <target name="publishedapi">

@@ -442,37 +442,25 @@

~   </target>

- -  <target name="javadocsubpackages">
- -    <java classname="com.sun.tools.javadoc.Main" fork="yes">
- -      <classpath path="${java.home}/../lib/tools.jar;${out.dir}"/>
- -      <jvmarg value="-mx320M"/>
- -      <arg value="-subpackages"/>
- -      <arg value="org"/>
- -      <arg value="-private"/>
- -      <arg value="-breakiterator"/>
- -      <arg value="-sourcepath"/>
- -      <arg value="${javadoc.sourcepath}"/>
- -      <arg value="-classpath"/>
- -      <arg value="${javadoc.classpath}"/>
- -      <arg value="-d"/>
- -      <arg value="${javadoc.destdir}"/>
- -      <arg value="-windowtitle"/>
- -      <arg value="${javadoc.windowtitle}"/>
- -      <arg value="-doctitle"/>
- -      <arg value="${javadoc.doctitle}"/>
- -      <arg value="-bottom"/>
- -      <arg value="${javadoc.bottom}"/>
- -      <arg value="-taglet"/>
- -      <arg value="org.apache.derbyBuild.javadoc.FormatIdTaglet"/>
- -      <arg value="-taglet"/>
- -      <arg value="org.apache.derbyBuild.javadoc.PurposeTaglet"/>
- -      <arg value="-taglet"/>
- -      <arg value="org.apache.derbyBuild.javadoc.UpgradeTaglet"/>
- -      <arg value="-taglet"/>
- -      <arg value="org.apache.derbyBuild.javadoc.DiskLayoutTaglet"/>
- -      <arg value="-taglet"/>
- -      <arg value="org.apache.derbyBuild.javadoc.EndFormatTaglet"/>
- -    </java>
+  <target name="javadocsubpackages" depends="build">
+    <javadoc
+        additionalparam="-J-mx320M"
+        packagenames="org.*"
+        access="private"
+        breakiterator="yes"
+        sourcepath="${javadoc.sourcepath}"
+        classpath="${javadoc.classpath}"
+        destdir="${javadoc.destdir}"
+        windowtitle="${javadoc.windowtitle}"
+        doctitle="${javadoc.doctitle}"
+        bottom="${javadoc.bottom}"
+        source="1.4" >
+        <taglet name="org.apache.derbyBuild.javadoc.FormatIdTaglet"
path="${basedir}/classes"/>
+        <taglet name="org.apache.derbyBuild.javadoc.PurposeTaglet"
path="${basedir}/classes"/>
+        <taglet name="org.apache.derbyBuild.javadoc.UpgradeTaglet"
path="${basedir}/classes"/>
+        <taglet name="org.apache.derbyBuild.javadoc.DiskLayoutTaglet"
path="${basedir}/classes"/>
+        <taglet name="org.apache.derbyBuild.javadoc.EndFormatTaglet"
path="${basedir}/classes"/>
+    </javadoc>
~   </target>

~   <target name="cleandocs">
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (MingW32)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iQEVAwUBQS6Ld3FDePgyse5HAQLyZwf9HEkwqfqfXlr+8VF3+Jt0YrNzs25nS9H7
CHrFXlC1zbnw8vi5HhV/XJS9aiL9KbiG98xEEVE4bQpo55PcQwGkTUA0w9dPQfAt
v01gbuoQC2CM7xXS8oNIkBzYGodVDh/rA24XQ4MgQmHJzIxWAA7dxEZHrO9UqSLz
d4EG/mso8Rj4ThxyD0IpTNkKKK9JeuJwWFRTg7viKn1fiYvblgRWH7en+hXAFV9d
4M00WPB2qxV3HbuYWiptEmV+lkc2vX8dXPZ61Y4Cv3KVzm8389OyCPWLEC5soX+I
MWm18WVPIlE9THhsX7kDY8kvoRWUmmE2m+qLPYK7YsJv/OM0ulYRlA==
=IoH2
-----END PGP SIGNATURE-----

Re: [PATCH] Various fixes to javadoc generation

[Andrew McIntyre <fu...@sbcglobal.net>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Committed as revision 47604.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (Darwin)

iD8DBQFBYyNmDfB0XauCH7wRAvWiAJwKMu/Ib8QJwcor5FfYaYf32HVbHQCfZU8V
Ux3Aur7PVM3QYpK5X9nqt64=
=nOp2
-----END PGP SIGNATURE-----

Re: [PATCH] Various fixes to javadoc generation

[Samuel Andrew McIntyre <fu...@nonintuitive.com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Jan,

Thank you! The problem was not the JVM memory parameter but how to  
specify the source packages without having to pass in a full list of  
the packages to be javadoc'd. I must have tried a dozen different ways  
to do it, none of which Ant or javadoc would accept. I'm pretty sure I  
tried several different combinations of org.*, but I guess I was  
determined to pass it to <javadoc> in an attribute for the source  
files/packages that doesn't like wildcards. I finally gave up and just  
called javadoc with <java> because that took me less time to figure  
out. :)

With that fixed, the subpackages target is no longer necessary, so that  
can be removed and the remainder consolidated to the derbydocs target.  
Below is an updated patch which consolidates the targets and fixes a  
couple of other little nits.

I'd like to check this in. I guess now would be a good time to discuss  
whether Derby should follow the 'commit then review' or the 'review  
then commit' style for applying patches.

Thanks again,
Andrew


Index: tools/ant/properties/dirs.properties
  ===================================================================
  --- tools/ant/properties/dirs.properties (revision 37102)
  +++ tools/ant/properties/dirs.properties (working copy)
  @@ -8,6 +8,7 @@
  src.dir=${basedir}
  javasrc.dir=${src.dir}/java
  javatools.dir=${src.dir}/tools/java
  +javadoctools.dir=${src.dir}/tools/javadoc
  javacom.dir=${javasrc.dir}/${com.dir}
  functest.dir=${javacom.dir}/functionTests
  locales.dir=${javacom.dir}/locales
  @@ -17,7 +18,7 @@
  class.dir=classes
  out.dir=${basedir}/${class.dir}
  outcom.dir=${out.dir}/${com.dir}
  -out.javadocs.dir=${basedir}/html
  +out.javadoc.dir=${basedir}/javadoc
  out.testdir=${basedir}/testout_${jdk}
  loc.dir=${out.dir}/org/apache/derby/loc
  drdaloc.dir=${out.dir}/org/apache/derby/loc/drda
  @@ -33,10 +34,10 @@
  oscom.dir=com/ihost/cs
  ossrc.dir=${basedir}/java

  -derby.engine.src.dir=${derbysrc.dir}/engine/
  -derby.drda.src.dir=${derbysrc.dir}/drda/
  -derby.tools.src.dir=${derbysrc.dir}/tools/
  -derby.build.src.dir=${derbysrc.dir}/build/
  +derby.engine.src.dir=${derbysrc.dir}/engine
  +derby.drda.src.dir=${derbysrc.dir}/drda
  +derby.tools.src.dir=${derbysrc.dir}/tools
  +derby.build.src.dir=${derbysrc.dir}/build

  derby.engine.dir=${derby.engine.src.dir}/${derby.dir}
  derby.drda.dir=${derby.drda.src.dir}/${derby.dir}
  Index: build.xml
  ===================================================================
  --- build.xml (revision 37102)
  +++ build.xml (working copy)
  @@ -354,79 +354,94 @@

  <target name="publishedapi">

  - <delete dir="${basedir}/javadoc/publishedapi"/>
  - <delete dir="${basedir}/javadoc/sourcedir"/>
  - <mkdir dir="${basedir}/javadoc/publishedapi"/>
  - <mkdir dir="${basedir}/javadoc/sourcedir"/>
  + <delete dir="${out.javadoc.dir}/publishedapi"/>
  + <delete dir="${out.javadoc.dir}/sourcedir"/>
  + <mkdir dir="${out.javadoc.dir}/publishedapi"/>
  + <mkdir dir="${out.javadoc.dir}/sourcedir"/>

  <!-- drda files -->
  - <mkdir dir="${basedir}/javadoc/sourcedir"/>
  - <copy todir="${basedir}/javadoc/sourcedir">
  + <mkdir dir="${out.javadoc.dir}/sourcedir"/>
  + <copy todir="${out.javadoc.dir}/sourcedir">
  <fileset dir="${derby.drda.src.dir}"
  includesfile="${javadoctools.dir}/publishedapi.ant"/>
  </copy>

  <!-- engine files -->
  - <copy todir="${basedir}/javadoc/sourcedir">
  + <copy todir="${out.javadoc.dir}/sourcedir">
  <fileset dir="${derby.engine.src.dir}"
  includesfile="${javadoctools.dir}/publishedapi.ant"/>
  </copy>

  <!-- tools files -->
  - <copy todir="${basedir}/javadoc/sourcedir">
  + <copy todir="${out.javadoc.dir}/sourcedir">
  <fileset dir="${derby.tools.src.dir}"
  includesfile="${javadoctools.dir}/publishedapi.ant"/>
  </copy>

  - <javadoc sourcepath="${basedir}/javadoc/sourcedir/"
  + <javadoc sourcepath="${out.javadoc.dir}/sourcedir/"
  classpath="${compile.classpath};${osgi};${servlet22};${out.dir}"
  breakiterator="true"
  - destdir="${basedir}/javadoc/publishedapi"
  + destdir="${out.javadoc.dir}/publishedapi"
   
packagenames="org.apache.derby.authentication,org.apache.derby.drda,org. 
apache.derby.jdbc.io,org.apache.derby.jdbc,org.apache.derby.tools"
  Windowtitle="Apache Derby ${major}.${minor} API Documentation"
  Doctitle="Apache Derby ${major}.${minor} API Documentation"
  bottom="Apache Derby ${major}.${minor} API Documentation -  
&lt;i&gt;Copyright &amp;copy; IBM Corp. 1997,2004 All Rights  
Reserved.&lt;/i&gt;"/>

  - <delete dir="${basedir}/javadoc/sourcedir"/>
  + <delete dir="${out.javadoc.dir}/sourcedir"/>

  </target>

  <target name="derbydocs">

  - <delete dir="${basedir}/javadoc/engine"/>
  - <mkdir dir="${basedir}/javadoc/engine"/>
  + <delete dir="${out.javadoc.dir}/engine"/>
  + <mkdir dir="${out.javadoc.dir}/engine"/>

  - <antcall target="javadocsubpackages">
  - <param name="javadoc.sourcepath"  
value="${derby.engine.src.dir};${derby.drda.src.dir};${derby.tools.src.d 
ir}"/>
  - <param name="javadoc.classpath"  
value="${basedir}/ 
classes;${java14compile.classpath};${jars.extras};${osgi}"/>
  - <param name="javadoc.destdir" value="${basedir}/javadoc/engine"/>
  - <param name="javadoc.subpackages" value="org.apache.derby"/>
  - <param name="javadoc.doctitle" value="Apache Derby  
V${major}.${minor} Engine Documentation"/>
  - <param name="javadoc.windowtitle" value="Apache Derby  
V${major}.${minor} Engine Documentation"/>
  - <param name="javadoc.bottom" value="Apache Derby V${major}.${minor}  
Engine Documentation - &lt;i&gt;Copyright &amp;copy; IBM Corp.  
1997,2004 All Rights Reserved.&lt;/i&gt;"/>
  - </antcall>
  + <javadoc
  + additionalparam="-J-mx320M"
  + packagenames="org.*"
  + access="private"
  + breakiterator="yes"
  +  
sourcepath="${derby.engine.src.dir};${derby.drda.src.dir};${derby.tools. 
src.dir}"
  +  
classpath="${basedir}/ 
classes;${java14compile.classpath};${jars.extras};${osgi}"
  + destdir="${out.javadoc.dir}/engine"
  + windowtitle="Apache Derby V${major}.${minor} Engine Documentation"
  + doctitle="Apache Derby V${major}.${minor} Engine Documentation"
  + bottom="Apache Derby V${major}.${minor} Engine Documentation -  
&lt;i&gt;Copyright &amp;copy; IBM Corp. 1997,2004 All Rights  
Reserved.&lt;/i&gt;"
  + source="1.4">
  + <taglet name="org.apache.derbyBuild.javadoc.FormatIdTaglet"
  +path="${basedir}/classes"/>
  + <taglet name="org.apache.derbyBuild.javadoc.PurposeTaglet"
  +path="${basedir}/classes"/>
  + <taglet name="org.apache.derbyBuild.javadoc.UpgradeTaglet"
  +path="${basedir}/classes"/>
  + <taglet name="org.apache.derbyBuild.javadoc.DiskLayoutTaglet"
  +path="${basedir}/classes"/>
  + <taglet name="org.apache.derbyBuild.javadoc.EndFormatTaglet"
  +path="${basedir}/classes"/>
  + </javadoc>
  +
  </target>

  <target name="toolsdocs">

  - <delete dir="${basedir}/javadoc/tools"/>
  - <mkdir dir="${basedir}/javadoc/tools"/>
  + <delete dir="${out.javadoc.dir}/tools"/>
  + <mkdir dir="${out.javadoc.dir}/tools"/>

  <antcall target="dojjdocs">
  <param name="jjtodoc" value="${derby.tools.dir}/impl/tools/ij/ij.jj"/>
  - <param name="jjdoctarget" value="${basedir}/javadoc/tools/ij.html"/>
  + <param name="jjdoctarget" value="${out.javadoc.dir}/tools/ij.html"/>
  </antcall>

  </target>

  <target name="grammardocs">

  - <delete dir="${basedir}/javadoc/language"/>
  - <mkdir dir="${basedir}/javadoc/language"/>
  + <delete dir="${out.javadoc.dir}/language"/>
  + <mkdir dir="${out.javadoc.dir}/language"/>

  <antcall target="dojjdocs">
  <param name="jjtodoc"  
value="${derby.engine.dir}/impl/sql/compile/sqlgrammar.jj"/>
  - <param name="jjdoctarget"  
value="${basedir}/javadoc/language/sqlgrammar.html"/>
  + <param name="jjdoctarget"  
value="${out.javadoc.dir}/language/sqlgrammar.html"/>
  </antcall>

  </target>
  @@ -442,42 +457,9 @@

  </target>

  - <target name="javadocsubpackages">
  - <java classname="com.sun.tools.javadoc.Main" fork="yes">
  - <classpath path="${java.home}/../lib/tools.jar;${out.dir}"/>
  - <jvmarg value="-mx320M"/>
  - <arg value="-subpackages"/>
  - <arg value="org"/>
  - <arg value="-private"/>
  - <arg value="-breakiterator"/>
  - <arg value="-sourcepath"/>
  - <arg value="${javadoc.sourcepath}"/>
  - <arg value="-classpath"/>
  - <arg value="${javadoc.classpath}"/>
  - <arg value="-d"/>
  - <arg value="${javadoc.destdir}"/>
  - <arg value="-windowtitle"/>
  - <arg value="${javadoc.windowtitle}"/>
  - <arg value="-doctitle"/>
  - <arg value="${javadoc.doctitle}"/>
  - <arg value="-bottom"/>
  - <arg value="${javadoc.bottom}"/>
  - <arg value="-taglet"/>
  - <arg value="org.apache.derbyBuild.javadoc.FormatIdTaglet"/>
  - <arg value="-taglet"/>
  - <arg value="org.apache.derbyBuild.javadoc.PurposeTaglet"/>
  - <arg value="-taglet"/>
  - <arg value="org.apache.derbyBuild.javadoc.UpgradeTaglet"/>
  - <arg value="-taglet"/>
  - <arg value="org.apache.derbyBuild.javadoc.DiskLayoutTaglet"/>
  - <arg value="-taglet"/>
  - <arg value="org.apache.derbyBuild.javadoc.EndFormatTaglet"/>
  - </java>
  - </target>
  -
  <target name="cleandocs">

  - <delete dir="${basedir}/javadoc"/>
  + <delete dir="${out.javadoc.dir}"/>

  </target>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (Darwin)

iD8DBQFBLt5HDfB0XauCH7wRAvKJAKCKcMJRrB7FCXoCizRDBjbP5Y4r1QCfflUL
cPqdrzsgEreDK7Sv+mZUo1U=
=HOoF
-----END PGP SIGNATURE-----