Package org.jdrupes.mdoclet.internal

package org.jdrupes.mdoclet.internal
The implementation of the javadoc tool and associated doclets.

Internally, javadoc is composed of two primary parts: the

Ungültige Referenz 
tool
, and a series of doclets.

The tool provides a common infrastructure for command-line processing, and for reading the declarations and documentation comments in Java source files, while doclets provide a user-selectable backend for determining how to process the declarations and their documentation comments.

The following provides a top-down description of the overall javadoc software stack.

Doclets
The Standard Doclet

The StandardDoclet is a thin public wrapper around the internal HTML doclet. 

    <dt id="html-doclet">The HTML Doclet
    <dd><p>
      The HtmlDoclet class
      and other classes in the
      formats.html package
      customize the abstract pages generated by the toolkit layer to generate
      HTML pages.  Some pages are specific to the HTML output format,
      and do not have an abstract builder in the toolkit layer.

      <p>Individual pages of output are generated by page-specific subtypes of
      HtmlDocletWriter.

      <p>The HtmlConfiguration class
      provides configuration information that is relevant to all the generated pages.
      The class extends the BaseConfiguration
      class provided by the toolkit layer.

      <p>The classes in the formats.html package use an internal
      library in the
      formats.html.markup package,
      to create trees (or acyclic graphs) of
      HTML tree nodes.
      Apart from using a common format-neutral supertype,
      Content, the markup library
      is mostly independent of the rest of the javadoc software stack.

    <dt id="toolkit">Toolkit
    <dd><p>
      The toolkit package provides
      support for a format-neutral
      abstract doclet,
      which uses
      builders
      to generate pages of abstract
      content.

      <p>The format-specific content for each page is provided by implementations
      of various <em>writer</em> interfaces, created by a format-specific
      writer factory.

      <p>The BaseConfiguration provides
      configuration information that is relevant to all the generated pages.
      Some of the information is provided by abstract methods which are implemented
      in format-specific subtypes of the class.

      <p>The toolkit layer also provides
      utility classes
      used by this layer and by format-specific layers.

      <p id="workarounds">Generally, it is intended that doclets should use the
      Language Model API to navigate the structure of a Java program,
      without needing to access any internal details of the underlying <em>javac</em> implementation.
      However, there are still some shortcomings of the Language Model API,
      and so it is still necessary to provide limited access to some of those internal details.
      Although not enforceable by the module system, by design the access to <em>javac</em>
      internal details by doclets based on AbstractDoclet is restricted to the aptly-named
      WorkArounds class.

    <dt>Other Doclets
    <dd><p>
      Doclets are obviously not required to use
      AbstractDoclet and other classes in
      the toolkit layer. In times past, it was common to write doclets to analyze
      code using the then-current API as an early version of a Java language model.
      That old API has been replaced by the Language Model API,
      and tools that wish to use that API to analyze Java programs have a choice of
      how to invoke it, using the <em>javac</em> support for
      annotation processing,
      or plugins, as well as doclets.
      Which is best for any application will depend of the circumstances, but
      if a tool does not need access to the documentation comments in a program,
      it is possible that one of the other invocation mechanisms will be more convenient.

  </dl>
The Doclet Interface

The Doclet API is the interface layer between the javadoc tool and the code to process the elements specified to the tool. 

 <p>Above this layer, in any doclet, the code is expected to use the
 Language Model API to navigate around the specified
 elements, and/or the DocTree API to examine
 the corresponding documentation comments.
The javadoc Tool

After reading the command-line options, the tool uses a modified javac front end to read the necessary files and thus instantiate the elements to be made available to the doclet that will be used to process them. 

   The tool uses an internal feature of the <em>javac</em> architecture, which
   allows various components to be replaced by subtypes with modified behavior.
   This is done by pre-registering the desired components in the <em>javac</em>
   Context.
   The tool uses this mechanism to do the following:
   <ul>
     <li>although source files are parsed in their entirety, the
       content of method bodies is quickly discarded as unnecessary;
     <li>the class reader is updated to handle package.html
       files in any package directories that are read; and
     <li>the compilation pipeline for each source file is terminated
       after the <em>parse</em> and <em>enter</em> phases, meaning that
       the files are processed enough to instantiate the elements to
       be made available to the doclet, but no more.
   </ul>

This is NOT part of any supported API. If you write code that depends on this, you do so at your own risk. This code and its internal interfaces are subject to change or deletion without notice.

Siehe auch: