Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8312044

Simplify toolkit Builder/Writer world



    • Enhancement
    • Resolution: Fixed
    • P4
    • 22
    • 21
    • tools


      Part of the internal architecture of the Standard Doclet is

      1. a split between a format-neutral `toolkit` layer and a format-specific `formats.html` layer
      2. a split between a `builder` class and a corresponding `writer` interface.

      The architectural split was more interesting in times long past, when there was interest/support for generating alternative formats: most notably formats used by the old `FrameMaker` documentation program, in order to generate hard-copy books, like this one: https://www.amazon.com/Java-Class-Libraries-java-lang-java-math/dp/0201310023 , and when the builder support was dynamically configurable by a user-supplied XML file, that specified the sections to be generated, and the order in which to generate them.

      There is no longer any interest in generating the content for hard-copy books, and the support for FrameMaker output formats was dropped long ago, even before the rewrite of the Standard Doclet in JDK 9. Likewise, the support for configuring pages using an XML file was also dropped a long while back, in favor of allowing users to provide subtypes of builders that override the default implementation of build methods.

      It is noted that the _use_ of the architecture is incomplete, and only applies to the basic pages for module, package, type and member declarations (generally, characterized as those pages needed for hard-copy books!). The "auxiliary" pages, like Class Use, Class Tree, Index, etc, do *not* have toolkit-level builders.

      Finally, it is noted that the nomenclature is inconsistent, especially for subtypes, using a mix of `Html---` and `---Impl` names in the `formats.html` directory.


        Issue Links



              jjg Jonathan Gibbons
              jjg Jonathan Gibbons
              0 Vote for this issue
              4 Start watching this issue