javajavadoctaglet

Loading the class in a custom JavaDoc Taglet?


I am writing a custom JavaDoc Taglet, and want to load and create an instance of the class for which the JavaDoc is being processed. This is the code I have (public class CDKIOOptionsTaglet implements Taglet):

public String toString(Tag tag) {
    return "<DT><B>IO options: </B><DD>"
           + expand(tag) + "</DD>\n";
}

public String toString(Tag[] tags) {
    if (tags.length == 0) {
        return null;
    } else {
        return toString(tags[0]);
    }
}

private String expand(Tag tag) {
    // create a table with IOOptions
    StringBuffer tableContent = new StringBuffer();
    SourcePosition file = tag.position();
    String pathAndFile = file.file().toString();
    pathAndFile = pathAndFile.replaceAll("/", ".");
    pathAndFile = pathAndFile.substring(pathAndFile.indexOf("src.main") + 9);
    pathAndFile = pathAndFile.substring(0, pathAndFile.indexOf(".java"));
    try {
        Class ioClass = Class.forName(pathAndFile);
        Object ioInstance = ioClass.newInstance();
        if (ioInstance instanceof IChemObjectIO) {
            IChemObjectIO objectIO = (IChemObjectIO)ioInstance;
            tableContent.append("<table>");         
            for (IOSetting setting : objectIO.getIOSettings()) {
                tableContent.append("<tr>");
                tableContent.append("<td>" + setting.getName() + "</td>");
                tableContent.append("<td></td>");
                tableContent.append("</tr>");
            }
            tableContent.append("</table>");
        }
    } catch (Exception e) {
        e.printStackTrace();
        return "";
    }
    return tableContent.toString();
}

And this is the Ant script including the jars in which the class to be loaded is added to the classpath used during the call:

<classpath>
  <pathelement location="." />
  <fileset dir="dist/jar">
    <include name="*.jar" />
  </fileset>
  <javadoc ...>
</classpath>

The jars where the classes I am creating JavaDoc for reside in dist/jar. For completeness (and upon request), here's the full call:

    <javadoc destdir="${javadoc.dir}"
             author="true" version="true" use="true"
             public="true"
             windowtitle="CDK API - version ${TODAY_SVN}">
        <classpath>
            <pathelement location="." />
            <fileset dir="dist/jar">
                <include name="*.jar" />
            </fileset>
            <fileset dir="jar">
                <include name="*.jar" />
            </fileset>
            <fileset dir="jar/jena">
                <include name="*.jar" />
            </fileset>
             <dirset dir="src/main">
                 <include name="net/**/*"/>
             </dirset>
        </classpath>
        <tag name="cdk.set" scope="all" description="Belongs to the set:" />
        <tag name="cdk.keyword" scope="all" description="Keywords:" />
        <tag name="cdk.created" scope="all" description="Created on:" />
        <tag name="cdk.require" scope="all" description="Requires:" />
        <tag name="cdk.depends" scope="all" description="Required library to be able to run this class:" />
        <tag name="cdk.builddepends" scope="all" description="Required library to be able to compile this class:" />
        <tag name="cdk.todo" scope="all" description="To do:" />
        <tag name="cdk.license" scope="all" description="License:" />
        <taglet name="net.sf.cdk.tools.doclets.CDKCiteTaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKModuleTaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKBugTaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKDictRefTaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKInChITaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKThreadSafeTaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKThreadNonSafeTaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKGitTaglet" path="jar/xom-1.1.jar:src/main" />
        <taglet name="net.sf.cdk.tools.doclets.CDKIOOptionsTaglet" path="jar/xom-1.1.jar:src/main" />
        <packageset dir="${src}/main" defaultexcludes="yes">
            <include name="org/openscience/cdk/**" />
        </packageset>
            <link href="${javaURL}"/>
    </javadoc>

I confirmed with "ant -v" that the appropriate jar indeed included the class that is being loaded. Still, I get this stacktrace:

[javadoc] java.lang.ClassNotFoundException: org.openscience.cdk.Atom
[javadoc]     at java.net.URLClassLoader$1.run(URLClassLoader.java:217)
[javadoc]     at java.security.AccessController.doPrivileged(Native Method)
[javadoc]     at java.net.URLClassLoader.findClass(URLClassLoader.java:205)
[javadoc]     at java.lang.ClassLoader.loadClass(ClassLoader.java:321)
[javadoc]     at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:294)
[javadoc]     at java.lang.ClassLoader.loadClass(ClassLoader.java:266)
[javadoc]     at net.sf.cdk.tools.doclets.CDKIOOptionsTaglet.expand(CDKIOOptionsTaglet.java:104)
[javadoc]     at net.sf.cdk.tools.doclets.CDKIOOptionsTaglet.toString(CDKIOOptionsTaglet.java:83)
[javadoc]     at net.sf.cdk.tools.doclets.CDKIOOptionsTaglet.toString(CDKIOOptionsTaglet.java:91)
[javadoc]     at com.sun.tools.doclets.internal.toolkit.taglets.LegacyTaglet.getTagletOutput(LegacyTaglet.java:130)
[javadoc]     at com.sun.tools.doclets.internal.toolkit.taglets.TagletWriter.genTagOuput(TagletWriter.java:185)
[javadoc]     at com.sun.tools.doclets.formats.html.HtmlDocletWriter.printTags(HtmlDocletWriter.java:230)
[javadoc]     at com.sun.tools.doclets.formats.html.ClassWriterImpl.writeClassTagInfo(ClassWriterImpl.java:246)
[javadoc]     at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.buildClassTagInfo(ClassBuilder.java:287)

How can I get the Taglet to load the class for which it is creating JavaDoc so that I can use reflection (etc) to learn more about that class, and return that as part of the Taglet output?


Solution

  • The <classpath> configuration is not the right place to declare the classes that are instantiated. Since the taglets instantiate your classes, you need to add these classes to the taglets' classpaths:

    <taglet name="net.sf.cdk.tools.doclets.CDKCiteTaglet">
      <path>
        <pathelement location="." />
        <fileset dir="dist/jar">
          <include name="*.jar" />
        </fileset>
      </path>
    </taglet>
    

    On the command line, it should look something like this:

    javadoc \
      ...
      -taglet 'net.sf.cdk.tools.doclets.CDKCiteTaglet' \
      -tagletpath '/.../jar/xom-1.1.jar:/.../jar/my-lib1.jar:/.../jar/my-lib2.jar:...' \
      ...