JDK-4638723 : stddoclet: Refactor to maximize shared code for doclets emulating the stddoclet
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0_01
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2002-02-15
  • Updated: 2014-05-05
  • Resolved: 2003-09-26
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
5.0 tigerFixed
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. 

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: tiger FIXED IN: tiger INTEGRATED IN: tiger tiger-b22

PUBLIC COMMENTS Fixed. The doclet has been refactored. ###@###.### 2003-09-16

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