Fixed.  The doclet has been refactored.
 xxxxx@xxxxx  2003-09-16This is a request for refactoring of the standard doclet
implementation to pull out its algorithms and utilites to make them
available to other doclets that emulate the standard doclet.
This would be of interest to the MIF doclet, LaTex doclet, and others.

This refactoring would cover the generation of content and functionality
independent of its formatting markup:

Shared content -- such things as:
 - summary tables
 - details of packages, classes and members
 - inheritance trees (overview tree, package tree, class tree)
 - how names are qualified in links (@see, {@link}, argument types, return 
   types, etc)
 - constant values page, serialized form page

Shared functionality and utilities -- such things as:
 - how command line options are handled
 - custom tags and taglets
 - extending taglets to use standard inline tags
 - computing relative paths to the docroot

NOTE: We are careful not to call this an API or SPI, as it will
remain an implementation, providing the flexibility for future
extension and improvement.  Others may use the interfaces
and utilities at their own risk, knowing full well in advance
that they may change at any time without notice. 

N/A

> > > Could you fairly easily make a list of all the
> > > places (classes, interfaces, methods, fields) 
> > > where the MIF doclet depends on or calls the
> > > com.sun.tools.doclets or
> > > com.sun.tools.doclets.standard?
> >
> >  Here are some classes that would belong in
> >  that API:
> > 
> > - All of the classes and interfaces in
> >   com.sun.tools.doclets
> > 
> > - The following classes in
> >   com.sun.tools.doclets.standard:
> > 
> >  Extern.java
> >  Group.java
> > 
> > Should we just use com.sun.tools.doclets?  
> > Many of the files in that
> > package need to be cleaned up. 

> Should Extern.java and Group.java be moved up into
> the doclets package?
> 
> -Doug

Jamie wrote:
Yes, I think Extern.java and Group.java should
definitely be in the API.  They are very useful
classes.  Unfortunately, I had to copy both of them
from the standard doclet to the mif doclet to avoid
conflicts. 

Doug wrote:
The standard doclet has always been bundled with the javadoc
tool, so the versions moved in lock-step.  Therefore, it has 
been unnecessary to ensure the doclet is backward compatible.
Nobody tries running the 1.4 doclet with the 1.3 javadoc.
However, for unbundled doclets (MIF, doccheck, localization, 
all third-party doclets), it's necessary to run them on 
different versions of javadoc and have backward compatibility.

Jamie wrote:
> The MIF doclet does call the new method to get the
> static final constant.  However, it only makes the
> method call if -constantvaluespage is used.  This option
> should only be used with 1.4 or higher.  If we use it
> with 1.3 or lower, the doclet will crash.
>
> When we implement the "builder", maybe we can
> carefully write the code so that no new Doclet API
> methods are called when an older version of Javadoc is
> run.  This is the strategy I am using to make doccheck
> backward compatible.

We have been cleared by the Tiger planning committee to pursue
this feature.  Demoted to BUG status, as this is the easiest way 
to  fix all of the bugs in the MIF doclet.  See "Comments" field
for more details.
 xxxxx@xxxxx  2002-08-09

I am not sure that I would be impacted directly by this 
refactoring based on the comments here and in the javadoc 
forum.

However, it appears that some utility classes would be 
made available for doclets to make use of that might 
simplify their design.  I, would not be too motivated to 
use them though without some commitment to keeping them 
fairly constant in functionality.

The features of the language and the addition of tags that 
have specific functionality is the biggest maintenence 
issue.  This doesn't seem to propose anything that will 
allow me to have javadoc do anything, by default for new 
tags so that I don't have to update my tool everytime 
there are changes to the JavaDoc specification.

Definitely YES! Do it! I am currently working on a PDF
doclet, and I am sure that I'm rewriting many functions
again that already exist somewhere in Sun's code.

This would be a wonderful thing and well worth the effort 
required to port existing doclets. My client generates both 
HTML and PDF documentation, and I have developed and 
maintain custom standard and MIF doclets for our API 
documentation. Every new feature (customization) that I add 
must be duplicated in both the standard and MIF doclets, 
and because they are organized differently, this can often 
be time-consuming.

I've even considered whether it would be worth rewriting a 
custom doclet from scratch to essentially do this. But I 
will happily wait for 1.5 instead.

In response to greggwon, our goal would be for these utility
classes to maintain compatibility over time.  We would treat
these classes as if they were an API, by changing existing
functionality only for bugs or obvious feature enhancements, 
and deprecating, rather than removing, methods and classes
that we no longer use.  However, because they are internal
to the tool, and not part of the Java Platform runtime, they 
are not an API tested as part of Java compatibility.

It would be great to be able to extend the Standard doclet
more easily.  It seems by exposing a number of the call
backs to print the different sections, this wouldn't be too
difficult.

I think just as important (if not more so) would be to
change the Doclet API away from a static method to a proper
singleton design, and to stop calling System.exit().