United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4638723 stddoclet: Refactor to maximize shared code for doclets emulating the stddoclet
JDK-4638723 : stddoclet: Refactor to maximize shared code for doclets emulating the stddoclet

Details
Type:
Bug
Submit Date:
2002-02-15
Status:
Resolved
Updated Date:
2003-09-26
Project Name:
JDK
Resolved Date:
2003-09-26
Component:
docs
OS:
generic
Sub-Component:
doclet
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0_01
Fixed Versions:
5.0 (tiger)

Related Reports

Sub Tasks

Description
This 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. 

                                    

Comments
EVALUATION

> > > 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.
###@###.### 2002-08-09
                                     
2002-08-09
PUBLIC COMMENTS

Fixed.  The doclet has been refactored.
###@###.### 2003-09-16
                                     
2003-09-16
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger

FIXED IN:
tiger

INTEGRATED IN:
tiger
tiger-b22


                                     
2004-06-14



Hardware and Software, Engineered to Work Together