Write better Javadoc with links

August 10th, 2007 | by Tonny Kohar |

You build your application and public API, and now you want to publish or give your API Javadoc to others. But what happen is that your Javadoc API looks ugly because all the external link eg: link to standard Java class (String, JComponent, JPanel, etc) have no link at all and just plain text. See the image below

javadoc with no links

compare with

javadoc with links

In order to create the link, you need to declare the link properties as the example ant target below, the important is link offline tag. Adjust the path and url as necessary.

Note: You also need to have jdk Javadoc locally (jdk.docs.api.dir), so the javadoc could resolve the link properly and replace it with proper url that link to jdk.docs.api.href

<target name="javadoc" depends="init" description="generates the API documentation.">
    <property name="jdk.docs.api.href" value="http://java.sun.com/j2se/1.5.0/docs/api/"/>
    <property name="jdk.docs.api.dir" value="/opt/jdk-docs/api"/>
    <javadoc 
        destdir="${docs.api.dir}"
        author="false"
        version="false"
        use="true"
        windowtitle="${ant.project.name} API">
 
        <packageset dir="${source.dir}" defaultexcludes="yes" />
 
        <classpath>
            <pathelement location="${classes.dir}" />
            <pathelement location="${resources.dir}" />
            <path refid="lib.dir.classpath"/>
        </classpath>
 
        <doctitle><![CDATA[<h1>${ant.project.name} API Specification</h1>]]></doctitle>
        <bottom><![CDATA[<i>Copyright &copy; 2002-2007 Kiyut. All Rights Reserved.</i>]]></bottom>
        <group title="Kiyut Ekspos packages" packages="kiyut.ekspos*"/>
        <group title="Kiyut ImageIO packages" packages="kiyut.imageio*"/>
        <group title="Kiyut Swing packages" packages="kiyut.swing.*"/>
        <link offline="true" href="${jdk.docs.api.href}" packagelistLoc="${jdk.docs.api.dir}"/>
    </javadoc>
</target>

Tags: ,

  1. 1 Trackback(s)

  2. Aug 10, 2007: » Blog Archive » Write better Javadoc with links

You must be logged in to post a comment.