This discussion is archived
7 Replies Latest reply: Sep 16, 2010 12:51 AM by 843810 RSS

how to filter HTML javadoc output ?

843810 Newbie
Currently Being Moderated
Hi all,

I would like to create a specific HTML javadoc output for a given source code tree.
Each class or method to be displayed is tagged with a specific (proprietary) tag, and I would like to create a Javadoc HTML tree with ONLY these classes and methods. The other ones should not be available in the HTML output.

Is is possible simply ? or do I have to modify the original Javadoc sources, as I saw in many replies, and use directly this modified "standard" doclet ?

Last question, but not so simple : i would like my doclet to be compiled under both JDK 1.4 and 1.5.
Do I have to modify both original sources and create 2 different "tools.jar" files, one for each JDK ?

thanx in advance for any tips !
brgds,
Philippe
  • 1. Re: how to filter HTML javadoc output ?
    843810 Newbie
    Currently Being Moderated
    No, this capability is not built-in to Javadoc, nor is it easy to implement.
    Here is some information on a related topic: excluding classes and members:

    http://java.sun.com/j2se/javadoc/faq/#exclude

    If you don't need to use your own proprietary tags, you might consider yDoc.

    If you want to do it yourself, first realize that the standard doclet was refactored between JDK 1.4 and 1.5. It would be as much work to implement the change in 1.4 as in 1.5. The 1.4 doclet could be compiled
    under javac 1.4 or 1.5. The 1.4 doclet could be compiled under javac 1.5
    using "-source 1.4".

    I'm not sure if the 1.4 tools.jar file works with JDK 1.5, as there are slight differences in the Doclet API. The 1.5 tools.jar file will not work with JDK 1.4.

    There may be other options I don't know of.

    -Doug
  • 2. Re: how to filter HTML javadoc output ?
    843810 Newbie
    Currently Being Moderated
    thanx for your answer !
    so, now, here are some additional questions ;-) ...

    actually I have already written a piece of code using Javadoc API 1.4, and I discovered that most of this doclet code has to be rewritten from scratch if I want to use the javadoc tool from JDK 1.5.
    Is it right ?

    I then tried to compile this specific code using the 1.4 tools.jar with JDK 1.5, and it went fine, but how is it possible to run this doclet ?

    javadoc tool from JDK 1.5 does not like too much this situation !
    I think the 1.5 tools.jar is prepended to any classpath when starting javadoc tool, and the objects sent by the javadoc tool to the entry point of my doclet (start() method) is rather different from the old implementation...

    how could I achieve this, i.e. is it possible to start my specific doclet jar, with only the 1.4 tools.jar file ?

    thanx again for any help !
    brgds,
    Philippe
  • 3. Re: how to filter HTML javadoc output ?
    843810 Newbie
    Currently Being Moderated
    Yes, if your code depends on the standard doclet code, and not just the
    Doclet API, some of it would need to be rewritten between 1.4 and 1.5.
    The standard doclet was refactored to create a "toolkit" -- much of the code
    was moved around in order for this toolkit to be used by the MIF doclet.

    Javadoc 1.5 contains the following check in AbstractDoclet.java that
    prevents any doclet other than the standard HTML doclet from running.
    This check was added because the toolkit has not been developed
    enough, and the Java team did not want the toolkit API to be available
    yet.
    private static final String TOOLKIT_DOCLET_NAME = new    
        com.sun.tools.doclets.formats.html.HtmlDoclet().getClass().getName();
    
    private boolean isValidDoclet(AbstractDoclet doclet) {
        if (! doclet.getClass().getName().equals(TOOLKIT_DOCLET_NAME)) {
            configuration.message.error("doclet.Toolkit_Usage_Violation", 
                TOOLKIT_DOCLET_NAME); 
            return false;
        }
        return true;
    }
    So you could modify this source file to accept your doclet and compile and
    replace it with the one in tools.jar

    Alternatively, you could run your doclet using "java" rather than "javadoc",
    placing the 1.4 tools.jar file ahead of (or instead of) the 1.5 tools. jar file in
    the classpath. I do something like this:
    $ java -classpath "1.4tools.jar:1.5tools.jar" com.sun.tools.javadoc.Main <doclet_options>
    Please let us know if this works.

    -Doug
  • 4. Re: how to filter HTML javadoc output ?
    843810 Newbie
    Currently Being Moderated
    Did you have an success?
    Each class or method to be displayed is tagged with a specific (proprietary) >tag, and I would like to create a Javadoc HTML tree with ONLY these classes >and methods
    I want to do nearly the same but have no idea how to start.
  • 5. Re: how to filter HTML javadoc output ?
    843810 Newbie
    Currently Being Moderated
    Did anyone above have any success in doing this?

    I would also like to generate JavaDoc filtering out specify classes and methods.
    I've found "PublishedApiDoclet (http://developer.berlios.de/projects/padoclet/)", but did not test it yet.
  • 6. Re: how to filter HTML javadoc output ?
    843810 Newbie
    Currently Being Moderated
    For that matter, you may also look at this tool:

    http://www.filigris.com/products/docflex_javadoc/

    The free edition, called DocFlex/Doclet, is basically the ready-to-use Javadoc doclet
    that outputs both HTML (framed and single-file) and RTF JavaDoc.
    It is also able to filter any classes, methods and fields by any tags (as well as annotations).

    The full edition (DocFlex/Javadoc) will allow you to customize that doclet as you wish
    (as well as to design your own doclets)



    Leonid Rudy
    http://www.docflex.com
  • 7. Re: how to filter HTML javadoc output ?
    843810 Newbie
    Currently Being Moderated
    Did anyone above have any success in doing this?
    Yes, it works. I'm the author of PublishedApiDoclet. It is written to filter out specific classes and methods using custom tags. PublishedApiDoclet acts as a filtering proxy between the javadoc program and any normal doclet. It also contains a doclet to check the (filtered) javadoc for dangling
    references. PublishedApiDoclet works for Java 5 and 6 (publishedApiDoclet1.5-0.4.jar) and Java 2 (publishedApiDoclet1.4-0.3.jar). It is available on http://developer.berlios.de/projects/padoclet/. The downloadable jar-files contain the doclet, the documentation and the sources.