Doclet

HI,
I need to extend the Standard doclet to support a few new tags. In each generated class page, I'm going to print the full text of the tags with the method they apply to, print a summary of info in the tags in the class description area, and support an option to suppress most normal info and only print the stuff from my new tags.
I need a good, well-structured tutorial about modifying the Standard doclet so I don't have to spend hours figuring it all out. Does anybody know where I can find such a thing?
thnaks for the sugessions

Hi,
Please go through the following URL:
http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/overview.html
and the article at Javaworld
http://www.javaworld.com/javaworld/jw-08-2000/jw-0818-javadoc_p.html
Hope this will help you.
Anil.
Developer Technical Support
Sun Microsystems Inc,
http://www.sun.com/developers/support

Similar Messages

Unable to see Java 5 features from Doclet API

The Doclet API was extended in Java 5 for getting information in generics, but I have been unable to get it to work. For example, calling ClassDoc.typeParameters and typeParamTags always returns an empty array.
* @param <X> The X
public class Test<X> {
}And the Doclet is:
import com.sun.javadoc.*;
public class TestDoc extends Doclet {
    public static boolean start(RootDoc root) {
        for (ClassDoc cd : root.classes()) {
            System.out.println();
            System.out.println(cd);
            TypeVariable[] tv = cd.typeParameters();
         if (tv.length == 0) {
          System.out.println("No type parameters");
         } else {
          for (TypeVariable t : tv) {
              System.out.println("tv: " + t);
         ParamTag[] pt = cd.typeParamTags();
         if (pt.length == 0) {
          System.out.println("No type parameter tags");
         } else {
          for (ParamTag t : pt) {
              System.out.println("pt: " + t);
        return true;
}For the Test class, it always prints out:
No type parameters
No type parameter tagsI'm running version 1.5.0_05. Is there some magic flag that needs to get passed? I have been unable to see any evidence that the new Java 5 API does anything at all.

Implementing
     public static LanguageVersion languageVersion() {
          return LanguageVersion.JAVA_1_5;
in my extension doclet solved the problem. Is part of the transition documentation from javadoc 1.2 to javadoc 1.5, but can not easily be found, not even a useful hint link.

DocFlex/Javadoc 1.5.6, a multi-format doclet development tool and more

DocFlex/Javadoc is both a multi-format Javadoc Doclet and a rapid doclet development tool, which allows easy creation of professional quality Java API documentation generated by Javadoc in various output formats.
More in this article:
Key Features
Availability
This Version
What is DocFlex?
Main Concepts
Other Applications
Links
KEY FEATURES
Template-driven doclet architecture
- Actual doclets are created in the form of special templates interpreted by the DocFlex Doclet, which is the template interpreter / output generator wrapped in the form of a Javadoc Doclet.
- The high quality graphic Template Designer allows you to visually design most of things, whose development was possible so far only by direct Java coding.
- The templates are designed independently on a particular output format. All formatting is specified in some universal way using properties of template components. During the generation, it is rendered with the suitable features available in the selected output format.
- The elaborated support of template parameters (including multivalued list parameters). The parameters are defined and accessed within templates to adjust dynamic properties of template components. Most of options previously used to control an ordinary doclet now simply become template parameters!
- The possibility to call templates from one another. This feature (along with the template parameters) makes possible re-using the same templates for different tasks as well as organizing template libraries.
Data processing
- The entire Doclet API is represented in the form of a virtual XML document (called Doclet DSM), on which the designing and processing of all templates is based.
- Sophisticated capabilities for data querying and sorting based on an extension of XPath.
- Full support of new Java 5.0 language features: Generic Types, Enums, Annotations.
- Simultaneous support of Java 1.4 and Java 5.
Creating hyperlinks
- Generation of an extensive network of hyperlinks interconnecting the whole documentation.
- The hyperlinks can be generated in all output formats that support them (this currently includes HTML and RTF).
- The universal way of defining documentation cross-links based on the link/target keys specified in templates.
- In RTF, the cross-links can be generated in the form of page number references, which effectively makes them usable even in the printed documentation.
- In HTML, the possibility of loading several frame windows from a single hyperlink at once.
Universal support of various formatting techniques
- text formatting: fonts, colors, borders
- paragraph formatting: margins, pagination control, borders, colors
- border formatting: styles (solid, double, dashed, dotted), thickness, colors
- tables: arbitrary cell layouts, borders, nested tables
- lists: bulleted, numbered, delimited
- document fields (RTF): page number, number of pages, TOC, etc.
- page formatting: size, orientation, margins, headers/footers
- formatting styles
- rendering of embedded HTML, which means interpreting in non-HTML output formats (such as RTF) the HTML tags embedded in text data (e.g. documentation comments). Almost all HTML tags practically usable in doc-comments are supported.
Inserting images
- statically specified in templates
- dynamically, obtained by <img> tags found in Java comments
- supported image formats: GIF, PNG, JPG, WMF, EMF, BMP
Output formats
- HTML (both framed multi-file and single-file output)
- RTF (version 1.6 - supported since Word 2000).
- TXT (plain text), which may be particularly useful for various utilizations of the Java code information provided by the Doclet API generate XML files by it, or SQL files to import into a database).
Standard Template Set
- The ready-to-use Standard Template Set included in all editions of DocFlex/Javadoc allows you to immediately generate:
(*) The framed HTML Java API documentation similar to that generated by the standard Javadoc.
(*) The same documentation packed in a single HTML file.
(*) The unmatched quality RTF JavaDoc.
- Special features supported by standard templates:
(*) Excluding classes/methods/fields by custom tags and annotations.
(*) Selective omitting of package qualifiers.
(*) Selective documenting of custom tags (similar to -tag option of Standard Doclet).
- By modifying the standard templates, you can quickly customize the generated documentation according to your needs.
Doclet GUI
- Besides command line options, DocFlex Doclet supports an alternative user-friendly way to control the template-based doclets interactively -- the high quality Doclet GUI.
- The Doclet GUI starts with the Generator Dialog, where you can specify all general settings (such as the main template, the output format and the output directory), start the generation, track its progress and stop at any moment you need.
- The grid-tree-based Parameter Inspector invoked from the Generator Dialog for a selected template allows you to view the descriptions of all template parameters controlling the doclet and set their values according to the parameter data types.
- The generator options specific for the selected output format can be set in the corresponding Format Option Inspector (also invoked from the Generator Dialog).
- Once the generation is finished (or cancelled), you can start it again with different settings or a new main template without restarting the whole Javadoc.
Integrations
- With any system that runs Javadoc (in particular, see below)
- Apache Ant
- Apache Maven 2
- Eclipse
For lots more information, see DocFlex/Javadoc homepage: [http://www.filigris.com/products/docflex_javadoc/]
AVAILABILITY
DocFlex/Javadoc comes in two editions:
(1) The full edition called "DocFlex/Javadoc" as it is. This is commercial software, which includes all the implemented functionality.
(2) The reduced freeware edition called "DocFlex/Doclet". It includes only the output generator and can be used as an interpretor of any custom templates. It also includes the standard template set, which allows you to instantly use it as an HTML doclet (similar to the standard one, however with some special features) plus an excellent quality RTF doclet.
Both editions are available for downloads on the page: [http://www.filigris.com/downloads/]
THIS VERSION
New features:
- The template interpretor works 15-20% faster
- Improvement of RTF output
- Multi-valued (list) template parameters
- Custom elements
- Standard Templates: Selective documenting of custom tags (similar to -tag option of standard doclet)
For more details, see product Readme | Change Log on the downloads page: [http://www.filigris.com/downloads/]
WHAT IS DOCFLEX?
DocFlex is an innovative technology for development of high quality template-driven documentation/report generators by any kind of data obtained from various software applications via the Java APIs they provide.
MAIN CONCEPTS
The whole DocFlex technology is based on four generalizations:
(1) The mapping of an entire Java API onto a virtual XML-like representation made of some elements and attributes so as to process any such a representation in a universal way using techniques borrowed from the field of XML, like XPath (or more precisely, a conceptual analogue of XPath with some extensions not present in it).
(2) The abstract formatting concept based on four layouts (flow of text, flow of paragraphs or paragraph-like objects, tables and lists), which can be rendered in most modern document formats (e.g. HTML, RTF, XSL-FO etc.)
(3) The automatic generation of hyperlinks (or their page number reference equivalents) by matching the sets of keys produced from certain natural properties of the things (entities) being documented and hyper-linked.
(4) The representation of the object controlling structure of the output generator (made on the first three principles) in the form of a plain-text template with a possibility to create and edit such templates using a graphic Template Designer, which visualizes the controlling objects (now becoming template components) in a form resembling the output they will produce.
OTHER APPLICATIONS
In fact, DocFlex/Javadoc is not the only application of DocFlex technology. The following is a summary of other DocFlex software:
DocFlex/XML
The SDK and runtime environment for rapid development and execution of template-driven automatic documentation/report generators by any data obtained from XML files.
This is currently the most complex and advanced application of DocFlex technology. Actually, this tool can be considered a powerful alternative to XSLT. At least, it is definitely able to do what XSLT apparently not (for example, see XSDDoc below). We will publish a more detailed comparison DocFlex/XML versus XSLT with the next DocFlex/XML release, which is coming very soon.
DocFlex/XML home page: [http://www.filigris.com/products/docflex_xml/]
DocFlex/XML | XSDDoc
A template set for DocFlex/XML that implements a high quality W3C XML Schema documentation generator in HTML and RTF output formats.
For more details, please see: [http://www.filigris.com/products/docflex_xml/xsddoc/]
DocFlex/XML | WSDLDoc
A similar template set for DocFlex/XML that will implement a high-end WSDL documentation generator.
This product is not released yet.
DocFlex/Together
A template-driven documentation generator for [Borland Together|http://www.borland.com/us/products/together/] (which is a UML modeling tool).
This is the earliest application of DocFlex technology and probably the most beautiful one. It works only with Together Architect 1.x, which is now obsolete. Unfortunately, since Together 2005, Borland eliminated any open APIs (for unknown reasons). Because of this, further development of DocFlex/Together was impossible.
DocFlex/Together home page: [http://www.filigris.com/products/docflex_together/]
See also examples of the UML documentation generated with it: [http://www.filigris.com/products/docflex_together/examples/]
The future DocFlex/UML is going to generate something like this as well.
DocFlex/UML
A template-driven UML documentation generator based on [Eclipse EMF|http://www.eclipse.org/emf/]. This tool is in early development stage yet. In a sense, it will continue DocFlex/Together with the focus on integration with other UML tools that use Eclipse EMF.
LINKS
This original article can be found at:
[http://www.filigris.com/ann/docflex_javadoc_v1.5.6/]
DocFlex/Javadoc home page:
[http://www.filigris.com/products/docflex_javadoc/]
DocFlex/XML home page:
[http://www.filigris.com/products/docflex_xml/]
DocFlex/XML | XSDDoc, the XML schema documentation generator:
[http://www.filigris.com/products/docflex_xml/xsddoc/]
Free downloads:
[http://www.filigris.com/downloads/]

Now, DocFlex/Javadoc v1.4 has been released specifically dedicated to Linux (Mac OS X) support:
(*) Some early bugs have been fixed, which prevented it working properly under Linux.
(*) A special RTF option was introduced to generate OpenOffice.org friendly RTF (see below)
(*) Improved support for external document viewers.
(*) Now, DocFlex/Javadoc software includes the shell script files prepared to quickly install and launch it under Linux
New RTF option
A new RTF output option "Tune output for MS Word� has been introduced. This option, actually, allows switching off that very tuning (which until now was the default mode) to produce an RTF friendly to open with other non MS Word applications, e.g. OpenOffice.org Writer under Linux.
Read full announcement (and screenshot) by this link:
http://www.filigris.com/ann/docflex_javadoc_v1.4/
Regards,
Leonid Rudy
http://www.docflex.com

How to count number of lines inside methods() using the Doclet API

Wrote a custom doclet using the [Doclet API|http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/doclet/index.html ] .
The purpose for the doclet is to load Java source files and create stubs (which are identical Java source files but do not contain any method implementation details).
Instead, the method implementation details need to be replaced with blank lines...
public class MyDoclet {
     private static String TAB = "\t";
     public static boolean start(RootDoc root) {
          ClassDoc[] classes = root.classes();
          // Parse through class or interface
          for (ClassDoc clazz : classes) {
               Type superClass = clazz.superclassType();
               // Print Methods
               MethodDoc[] methods = clazz.methods();
               for (MethodDoc method : methods) {
                    Parameter[] parameters = method.parameters();
                    println();
                    if (!method.isPrivate()) {
                         print(TAB + method.modifiers() + " "
                                                + method.returnType().simpleTypeName() + " " + method.name());
                         print("(");
                         for (int i=0; i < parameters.length; i++) {
                              Parameter parameter = (Parameter) parameters;
                              print(parameter.type().simpleTypeName() + " " + parameter.name());
                              if (i != parameters.length - 1) {
                                   print(", ");
                         print(")");
                         println(" {");
                         println("\n");
                         println(TAB + "}");
          return true;
As one can see, I am just creating the method and placing the opening and closing curly braces (along with a new \n line escape sequence, in between).
Am not really that familiar with the Doclet API...
Question(s):
(1) What is the best way to figure out how many lines of code are inside each method and then use a for loop to insert the exact same number of blank lines inside the methods?
(2) Is there a way to do it using the com.sun.javadoc.SourcePosition.line() method?
Would really appreciate it if someone could help me because this is an important requirement (hence the 10 Duke Stars).
Happy coding to all,
Mike

This is not possible using the Doclet API, because JavaDoc does not store any information regarding implementation detail. Although MethodDoc#position will give you the line where the method is declared, there is no way to determine where the method body starts and ends.
If you need that much information, maybe you would be better of using a tool such as Eclipse's Abstract Syntax Tree parser. AST will provide you with line numbers for each code expression, hence it is relatively easy to compute the first and last line in a method body.

Subclassing standard doclet in version 1.4

I have a modified version of the standard doclet from 1.3.1. I'm trying to transfer the functionality from this doclet to a subclass of the 1.4.1 standard doclet. My modified Standard.java contains the following method:
public static ConfigurationExcluderDoclet configuration() {
if (HtmlDocWriter.configuration == null) {
HtmlDocWriter.configuration = new ConfigurationExcluderDoclet();
return (ConfigurationExcluderDoclet)(HtmlDocWriter.configuration);
This won't work in 1.4.1 as the variable "configuration" in HtmlWriter has been modified to protected access only. Is there a workaround for this so that I can still pass my configuration instance?
Thanks,
Linda Howard

Hi Linda,
Just delete the code below and replace with "return new ConfigurationExcluderDoclet();". There is absolutely no need to initialize HtmlDocWriter.configuration in your configuration() method. This field is now initialized in the constructor, as it should be. If you need to access the configuration in your doclet, use Standard.configuration, not HtmlDocWriter.configuration. Your doclet should inherit the configuration from class Standard.
-Jamie Ho

How to maintain standard doclet's Javadoc options in custom doclet?

I'm having some difficulties with a custom doclet. I've simply subclassed some of the standard doclet classes to do some custom html output (basically wrapping the output in the headers/footers/navigation of our department intranet). I want to use the standard doclet's configuration and a few of the standard doclet's Javadoc options (-nonavbar and -stylesheetfile, for example). I did not subclass ConfigurationStandard.java because I had no changes that I wanted to make to it. I'm not adding any new tags or command line options, but shouldn't I be able to use the standard doclet's command line options since I'm importing com.sun.tools.doclets.standard.*?

Does your main doclet class (which has the start(RootDoc method)) also contain the optionLength and validOptions method.
Check this url for more info http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/overview.html
If you are just supporitng the standard doclet optiosn then you can implement these methods in ur doclet and internally call the corresponding methods of the standard doclet to get things done.
public static int optionLength(String option) {
return Standard.optionLength(option);
public static boolean validOptions(String options[][], DocErrorReporter reporter) {
return Standard.validOptions(options, reporter);
}Hope it helps

Can't get "Simple Example Doclet" to run -- Cannot find

I am trying to run the "Simple Example Doclet" at http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/overview.html.
It appears to compile ok, but when I go to run it I get the message "javadoc: Cannot find doclet class ListClass".
Listed below is:
     1. The execution command and error message
     2. The version (output of javadoc -J-version)
     3. The javac compile command and input and output files
All directories have been kept the same as in the example.
Any help would be appreciated.
Thanks
1. C:\jdk1.3>javadoc -doclet ListClass -classpath C:\jdk1.3\lib\tools.jar MyClass.java
javadoc: Cannot find doclet class ListClass
1 error
2. javadoc -J-version
     gives
          java version "1.3.1_01"
          Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_01)
          Java HotSpot(TM) Client VM (build 1.3.1_01, mixed mode).
3. javac -classpath C:\jdk1.3\lib\tools.jar ListClass.java
     appears to give good compile ....
          e. g. Input source file ListClass.java is as follows:
               import com.sun.javadoc.*;
               public class ListClass {
               public static boolean start(RootDoc root) {
               ClassDoc[] classes = root.classes();
               for (int i = 0; i < classes.length; ++i) {
               System.out.println(classes);
               return true;
          and.....
          decompiled ListClass.class file is as follows:
               // Decompiled by DJ v2.8.8.54 Copyright 2000 Atanas Neshkov Date: 10/11/2001 4:09:46 PM
               // Home Page : http://members.fortunecity.com/neshkov/dj.html - Check often for new version!
               // Decompiler options: packimports(3)
               // Source File Name: ListClass.java
               import com.sun.javadoc.RootDoc;
               import java.io.PrintStream;
               public class ListClass
               public ListClass()
               public static boolean start(RootDoc rootdoc)
               com.sun.javadoc.ClassDoc aclassdoc[] = rootdoc.classes();
               for(int i = 0; i < aclassdoc.length; i++)
               System.out.println(aclassdoc[i]);
               return true;

Sorry to be so late in getting back to you .. I was on vacation.
ListClass is in the current directory. I did get it to work however... In order to get it to work I had to do two things:
1. use -docletpath (even thought it was in the current path) e. g. -docletpath C:\jdk1.3\ListClass.jar
AND
2. Make the class file a jar file -- I could not get it to work otherwise.
p.s. the typo was a decompiler error.

Steps for creating custom doclet

I'm a complete newbie to this whole JavaDoc Doclet stuff. I trying to create a custom Doclet I think. I want to use all the standard annotations but add 1 of my one aswell and a method so only the methods with my annotation is shown.
I have a custom Doclet from the sun tutorial but don't have it creating a html file in docs folder or have it recognising any of the standard annotations. It doesn't extend or implement anything.
Any advice on the step to take when creating a Doclet would be much appreciated.

Thanks for the reply Leonid, still confused do.
I'd like to create a HTML page that will show all the standard annotations/tags but also a custom tag. From the tutorial I have:
import com.sun.javadoc.*;
public class ListClass {
    public static boolean start(RootDoc root) {
         String tagName = "myTag";
         writeContents(root.classes(), tagName);
         return htmlDoclet.start(root);
         return true;
    private static void writeContents(ClassDoc[] classes, String tagName) {
         for (int i=0; i < classes.length; i++) {
            boolean classNamePrinted = false;
            MethodDoc[] methods = classes.methods();
for (int j=0; j < methods.length; j++) {
     Tag[] tags = methods[j].tags(tagName);
          if (tags.length > 0) {
          if (!classNamePrinted) {
          System.out.println("\n" + classes[i].name() + "\n");
          classNamePrinted = true;
          System.out.println(methods[j].name());
          for (int k=0; k < tags.length; k++) {
          System.out.println(" " + tags[k].name() + ": " + tags[k].text());
Should I be extending Standard or Doclet, I tried to extend Standard but it said it couldn't find myTag.
I read a few places it's probably easier to just create the whole Doclet thing from scratch but is very time consuming and seems a bit daunting to me.
I'm probably not making much sense but I'm a bit lost with all this.

Extending standard doclet by subclassing: impossible?

Hi,
I'd like to extend the standard html doclet so that a class diagram appears just below the class name in every doc file.
I want to do that for an open source project, so I have to do it in a way that allows the redistribution of the doclet.
As far as I understand the licence, I can do that only by subclassing (because using the standard doclet source would prevent redistribution, right?).
Problem is, the standard doclet in 1.5.0 has been designed so that it's almost impossible to extend by subclassing, because many classes have private constructors.
I just need to add a link after the html generated by ClassBuilder.buildClassHeader(), but I cannot subclass HTMLDoclet because I would incur in the check AbstractDoclet.isValidDoclet(), and there's no way to change the HTMLDoclet configuration neither.
In the FAQ (http://java.sun.com/j2se/javadoc/faq/index.html#sourcedoclet) you suggest that the preferred way to extend the standard doclet is by subclassing, but in my opinion you made every step to make it impossible in practice.
Is there any way to achieve my goal, besides rewriting the whole doclet? (which would be not practical, it's an open source project and I'm working in my spare time).

I don't share your vision of open sourceI would love to share your vision too. But the economics reality defies it! All we could do about that is just to understand the truth and to adapt to it (like engineers understand the physics and make the aircraft fly -- the thing seemingly to be impossible).
If you really want to implement your new ideas, you won't be able to do it in your spare time... you will need huge a lot of resources for doing that. But who will pay you? A guy with money would never give you a cent without looking at his own benefits... Be sure!
I'd simply buy yDocI know those guys quite enough... and that's exactly an example of a very much closed up company. We, on the contrary to them, are just looking forward for any integrations with the outside world !
But anyway, thank you for your offer :-) Well. If you are able to program the generation of the diagrams like yDoc does, DocFlex/Javadoc will be free for you! We just don't have time to do that ourselves. We could provide you a partner license. There's an DocFlex Open API (not published yet, but it's coming just soon). You can create you integration that generates those diagrams and insert them into the generated docs using your templates (all you would need is just to adapt the existing ones!), and then use/redistribute the whole thing together with the freeware DocFlex/Doclet engine as you like, in the open-source form or not. Everything you would have developed by yourself is yours!
Regards,
Leonid Rudy
http://www.docflex.com

Help in Custom Doclet

Hi,
I m trying to get going with my first doclet. I m using jdk 1.4 and it tools on MS-XP m/c.
I m able to process my tags in my doclet and able to create an HTML for a specific java file. But i wanted to know how i can use some features of the Standard doclet such as creation of index.html, displaying package summary , displaying class hierarchy etc. Is there a way to do this ?
Thx,
Atul

Sure, there is!
All you need is to write everything by yourself: walk the object model provided by Doclet API, fill in hash-table, sort out/trasform information, track hyperlinks, generated HTML files and so on and so on.
As far as I understand how Javadoc works, in fact, it is little more than a launcher of two things: the Java compiler contained in Java SDK and the Standrard doclet.
By writing your own doclet, you simply take over the second part for yourself.
Everything you wish to see in your output documentation is solely up to you to implement by yourself !
And this is not as easy to do if you want to generate the profesionally looking documentation. In fact, I believe, currently, only three ways exist:
(1) You can persued your bosses to allow you to develop your own doclet during some months (if you believe, you could successfully accomplish such a task)
(2) You may find the open-source implementation of an existing doclet, try to undestand how it works and to accomodate it for your own needs.
(3) At last, you can use DocFlex/Javadoc which is a unique tool that allows you to visually design doclets of any complexity able to generate the high quality HTML, RTF, and plain text output/documentation at once.
You can find the full information about this tool as well as download it by the following link:
http://www.filigris.com/products/docflex_javadoc/
Here are a few highlights:
The doclets are designed in the form of templates (whose internal structure is somewhat similar to XSLT scripts) using a high quality graphic Template Designer representing the templates in the WYSIWYG form that reflects the structure and the formatting of the generated output. The templates are interpreted by the DocFlex/Doclet engine which is also provided separately as a freeware edition supplied with the basic templates that besides other things can be used simply as a ready-to-use RTF generator for Javadoc.
The output is generated in HTML, RTF and TXT formats. The HTML may be both single-file and multi-framed documentation. The RTF is outstanding quality looking almost identical to the HTML produced by the default doclet with the correct rendering of most of the HTML tags embedded in Java comments (including inserting images and table markup) plus all pagination support such as page numbers and tables of contents.
The TXT output allows you to generate whatever else you wish, for instance, XML files or a secondary Java code produced from the primary one by special tags inserted in doc comments (which is similar to XDoclet functionality).
DocFlex/Javadoc was designed to meet needs of both people looking for a quick fix for a problem suddnely arised in their project as well as for demanding developers needed a professional tool.
You can enjoy using DocFlex/Javadoc only because it is one of the applications of a much more general technology aimed to various software development fields related to data retrieval and representation which made it worth to spend huge efforts to develop this.
Leonid Rudy
http://www.docflex.com

How to debug a custom doclet

Hi,
Can an incorrect taglet name cause javadoc generation to crash/ hang?
We have a custon taglet with the name of @abc.comment
However, someone added a period at the end of the name by mistake: @abc.comment.
This caused the cruise control build to crash...
Any clues on why this would have happened would be helpful. Also, how do you debug a custom doclet?
Thanks in advance.
BB

Also, how do you debug a custom doclet?Well, the usual way: you use a debugger ;-)
Since Javadoc features a programmatic interface, it's easy to write a simple main class.
Here is my test entry class, just replace "your.doclet.name.here" with the actual name of your custom doclet.
TestRun requires a filename as sole argument/cmd option, this filename should point to a standard Javadoc options file. To successfully use TestRun, the classes that make up your custom doclet and the JDK tools.jar should (probably) be in the classpath.
* @(#) TestRun.java 1.00
import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;
import java.util.StringTokenizer;
* <code>TestRun</code>
* @author Thomas Behr 27.11.2003
public class TestRun
    public static void main( final String[] args )
        if ( args.length != 1 || !(new java.io.File( args[0] )).isFile() )
            System.err.println( "usage: java TestRun <filename>" );
            return;
        com.sun.tools.javadoc.Main.execute( "javadoc",
                                            "your.doclet.name.here",
                                            processOptionsFile( args[0] ) );
    private static String[] processOptionsFile( final String filename )
        final String options = readOptionsFile( filename );
        final StringTokenizer tokens = new StringTokenizer( options );
        final String[] jargs = new String[tokens.countTokens()];
        for ( int i = 0; i < jargs.length; ++i )
            jargs[i] = tokens.nextToken();
        return jargs;
    private static String readOptionsFile( final String filename )
        final StringBuffer buffer = new StringBuffer();
        BufferedReader br = null;
        try
            br = new BufferedReader( new FileReader( filename ) );
            String line;
            while ( (line = br.readLine()) != null )
                buffer.append( line ).append( "\n" );
        catch ( final IOException ioe )
            ioe.printStackTrace();
            buffer.setLength( 0 );
        finally
            if ( br != null )
                try
                    br.close();
                catch ( IOException ioe )
                    ioe.printStackTrace();
        return buffer.toString();
}

Standard XSLT for Java(XML) Doclet

I've just found "Java Doclet" <http://wwws.sun.com/software/xml/developers/doclet> for generating XML documentation from Java source code files rather than generating HTML. It is just what I want because I can easily create customized HTML versions out of the XML using XSLT sheet.
I've wondered if there's available an XSLT for generating standard HTML just like the output of the standard doclet, to use as starting point for modifications?

BTW, the closest thing I can think of is xmlroff which uses the output of this
XML doclet to produce PDF (without cross-reference links, I believe)
http://xmlroff.sourceforge.net/
See the Javadoc example:
http://xmlroff.sourceforge.net/examples/javadoc/index.html
The source is at sourceforge:
http://sourceforge.net/projects/xmlroff/
Also now available on SourceForge is the related PangoPDF project at
http://pangopdf.sourceforge.net/
and
http://sourceforge.net/projects/pangopdf/
Please let me know what you think of these.
-Doug Kramer

Use of classes in com.sun.tools.doclets

Hello -- What is the best practice recommendation wrt using the classes in com.sun.tools.doclets -- particularly with the planned refactoring?
I'm writing a doclet that doesn't subclass, say, the standard doclet. There are obviously several very useful classes in this package (ClassTree, Util, MethodFinder, etc.) that I'd like to use. I can simply call their methods, but I'm curious to know if their active days are numbered.
Would it be better to simply incorporate the source? What are the restrictions on using the source in my own doclet?
If this is all covered somewhere (I've been hunting around a bit), please feel free to simply point me to the info.
Thanks!
Steve

The Java 2 SDK license (which covers javadoc) allows you to only
redistribute the code unmodified.
In 1.5.0, the refactoring has renamed all of the packages and
moved a lot of code around. We hope and plan to release
the refactored code on java.net around the time 1.5.0 is
released, and get an early access of it out. We'll notify
people who are on the javadoc-announce email address which
people can sign up as described at:
http://java.sun.com/j2se/javadoc/#forum
If you want more specific information now about how these will change,
please let me know and we can answer those questions.
-Doug Kramer
Javadoc team

How can I run my doclet from main method?

I want to run doclet from main method.
My source is:
command = String.format("%s%s%s%s",
"cmd /c ",
"% javadoc -doclet ",
"ExportJavaLib ",
"-private " + dir.getAbsolutePath() + ".java");
Runtime.getRuntime().exec(command);My doclet class file is in the same directory where is my class containing main method.
I run the main class from bat file and set
set CLASSPATH=%CLASSPATH%;D:\jdk1.5.0_06\lib\Tools.jarBut my code does nothing when it must execute the doclet.

I've done it. 10x :)

Error using MIF doclet to create PDFs

I have been attempting to use the dzbatcher program with framemaker and the java MIF doclet. Unfortunately, there is an error that will not allow the MIF doc to be saved as a pdf, the MIF files are created correctly.
Executing: dzbatcher -makername framemaker C:\JavaCode\VSan2.0\vsan\doc\customer\mif\mif-to-fm.batch...
starting maker ...
Waiting for Frame results... done.
Waiting for Frame results...
Frame reports error -42:
Cannot save file [C:\JavaCode\VSan2.0\vsan\doc\customer\fm\api.book.pdf]I have FrameMaker 5.5 and Acrobat Distiller and Exchange 3.1.
Any help would be deeply appreciated.
-Dustin

I've never encountered error -42. I've been bugging Adobe
for a list of descriptions for their numbered error message
to no avail.
The way to troubleshoot the batch file is to execute
the dzbatcher command with the -v (verbose) option
on the mif-to-fm.batch file:
dzbatcher -v C:\java\pubs\docs\mif\mif-to-fm.batch
This should echo every statement, so you can see where the
problem is occurring.
You might contact us for possible access to an early
release of the next version, which has some fixes in this
area. Write doccheck-feedback at java.sun.com.
If those ideas don't work, you could also follow EJP's advice,
or you could try sending email to dzbatcher at datazone.com.
They wrote dzbatcher and are pretty responsive.
We've had pretty good luck using dzbatcher with the default
template of the MIF Doclet.
Please let us know how you get it to succeed in case I can
pass along the pointer to others.
-Doug (Hi Esmond)

Doclet

Similar Messages

Maybe you are looking for