Building javadoc from J2SDK source code

If you read my last blog entry about J2SDK 1.5 alpha availability, you know you cannot make public comments about. So, with that information in mind, let's move on :-D

Suppose you download a J2SDK version from Sun that comes with no documentation at all. Well, all of them come without it, but for most you can get the docs as a separate bundle and install them. Very recently, I downloaded a J2SDK version for which there is no documentation at all. And no, you cannot download it from Sun's site; it is not there. How am I supposed to work with a JDK that has no documentation? At least, I can build javadoc from its source code and it becomes more usable - though not completely, as the new features summary and those sections where concepts are explained and detailed are necessary for a full experience :-D.

In case you happen to face the same problem - if you read my blog frequently, there is a chance you are :-D -, here is a sample Ant build script - not the best possible, it's not the point - you may use to build javadoc from source code:

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="javadoc">
    <target name="javadoc">
        <property name="jdk_root" value="JDK_HOME" />
        <mkdir dir="${jdk_root}/src" />
        <mkdir dir="${jdk_root}/docs" />
        <unzip dest="${jdk_root}/src" src="${jdk_root}/src.zip" />
        <path id="src">
            <fileset dir="${jdk_root}/src">
                <include name="java/**/*.java" />
                <include name="javax/**/*.java" />
                <include name="org/**/*.java" />
            </fileset>
        </path>
        <pathconvert pathsep=" " property="files" refid="src">
            <map from="${jdk_root}${file.separator}src${file.separator}" to=""/>
        </pathconvert>
        <echo message="${files}" file="${jdk_root}/srcs.txt"/>
        <exec dir="${jdk_root}/src" executable="${jdk_root}/bin/javadoc.PLATFORM_EXTENSION">
            <arg value="-protected" />
            <arg value="-source" />
            <arg value="JDK_MAJOR_VERSION" />
            <arg value="-d" />
            <arg value="${jdk_root}${file.separator}docs" />
            <arg value="-use" />
            <arg value="-author" />
            <arg value="-serialwarn" />
            <arg value="-J-Xmx512m" />
            <arg value="@${jdk_root}${file.separator}srcs.txt" />
        </exec>
    </target>
</project>

That is it, folks! Remember to edit the script so JDK_HOME becomes your real JDK installation home (ex: C:\j2sdk1.4.2_02), JDK_MAJOR_VERSION becomes the major version of the JDK you are using (ex: 1.4, 1.5 ...) and PLATFORM_EXTENSION becomes the extension used by executables in your platform (ex: for Windows, it's exe). And yeah, it consumes a lot of memory. You can change the value -J-Xmx512m as you want, but it didn't work for me with 128mb, for example. It took around 8 minutes to run it in a P4 2.4GHz with 1GB - hey, but I was making normal use of it (4 IM softwares, email client, etc.)