org.jdrupes.mdoclet.internal.package-info Maven / Gradle / Ivy
Show all versions of doclet Show documentation
/*
* Copyright (c) 2018, 2022, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* The implementation of the javadoc tool and associated doclets.
*
* Internally, javadoc is composed of two primary parts:
* the {@link org.jdrupes.mdoclet.internal.tool tool}, and a series of
* {@link org.jdrupes.mdoclet.internal.doclets 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 {@link jdk.javadoc.doclet.StandardDoclet} is a thin public wrapper
* around the internal HTML doclet.
*
*
- The HTML Doclet
*
* The {@link org.jdrupes.mdoclet.internal.doclets.formats.html.HtmlDoclet} class
* and other classes in the
* {@link org.jdrupes.mdoclet.internal.doclets.formats.html 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.
*
*
Individual pages of output are generated by page-specific subtypes of
* {@link org.jdrupes.mdoclet.internal.doclets.formats.html.HtmlDocletWriter}.
*
*
The {@link org.jdrupes.mdoclet.internal.doclets.formats.html.HtmlConfiguration} class
* provides configuration information that is relevant to all the generated pages.
* The class extends the {@link org.jdrupes.mdoclet.internal.doclets.toolkit.BaseConfiguration}
* class provided by the toolkit layer.
*
*
The classes in the {@code formats.html} package use an internal
* library in the
* {@link org.jdrupes.mdoclet.internal.doclets.formats.html.markup formats.html.markup} package,
* to create trees (or acyclic graphs) of
* {@linkplain org.jdrupes.mdoclet.internal.doclets.formats.html.markup.HtmlTree HTML tree nodes}.
* Apart from using a common format-neutral supertype,
* {@link org.jdrupes.mdoclet.internal.doclets.toolkit.Content}, the {@code markup} library
* is mostly independent of the rest of the javadoc software stack.
*
*
- Toolkit
*
* The {@link org.jdrupes.mdoclet.internal.doclets.toolkit toolkit} package provides
* support for a format-neutral
* {@linkplain org.jdrupes.mdoclet.internal.doclets.toolkit.AbstractDoclet abstract doclet},
* which uses
* {@linkplain org.jdrupes.mdoclet.internal.doclets.toolkit.builders.AbstractBuilder builders}
* to generate pages of abstract
* {@linkplain org.jdrupes.mdoclet.internal.doclets.toolkit.Content content}.
*
*
The format-specific content for each page is provided by implementations
* of various writer interfaces, created by a format-specific
* {@linkplain org.jdrupes.mdoclet.internal.doclets.toolkit.WriterFactory writer factory}.
*
*
The {@link org.jdrupes.mdoclet.internal.doclets.toolkit.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.
*
*
The toolkit layer also provides
* {@linkplain org.jdrupes.mdoclet.internal.doclets.toolkit.util utility classes}
* used by this layer and by format-specific layers.
*
*
Generally, it is intended that doclets should use the
* {@link javax.lang.model Language Model API} to navigate the structure of a Java program,
* without needing to access any internal details of the underlying javac 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 javac
* internal details by doclets based on {@code AbstractDoclet} is restricted to the aptly-named
* {@link org.jdrupes.mdoclet.internal.doclets.toolkit.WorkArounds} class.
*
*
- Other Doclets
*
* Doclets are obviously not required to use
* {@link org.jdrupes.mdoclet.internal.doclets.toolkit.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 {@link javax.lang.model 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 javac support for
* {@linkplain javax.annotation.processing annotation processing},
* or {@linkplain com.sun.source.util.Plugin 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.
*
*
*
* - The Doclet Interface
*
* The {@linkplain jdk.javadoc.doclet Doclet API} is the interface layer between
* the javadoc tool and the code to process the elements specified to the tool.
*
*
Above this layer, in any doclet, the code is expected to use the
* {@linkplain javax.lang.model Language Model API} to navigate around the specified
* elements, and/or the {@linkplain com.sun.source.doctree 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
* {@linkplain javax.lang.model.element.Element elements} to be made available to
* the doclet that will be used to process them.
*
* The tool uses an internal feature of the javac architecture, which
* allows various components to be replaced by subtypes with modified behavior.
* This is done by pre-registering the desired components in the javac
* {@code Context}.
* The tool uses this mechanism to do the following:
*
* - although source files are parsed in their entirety, the
* content of method bodies is quickly discarded as unnecessary;
*
- the class reader is updated to handle {@code package.html}
* files in any package directories that are read; and
*
- the compilation pipeline for each source file is terminated
* after the parse and enter phases, meaning that
* the files are processed enough to instantiate the elements to
* be made available to the doclet, but no more.
*
*
*
*
* 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.
*
* @see JavaDoc Architecture
* @see Using the new Doclet API
* @see Processing Code
*/
package org.jdrupes.mdoclet.internal;