mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-28 15:24:43 +02:00
8206318: Enhance package documentation for internal javadoc packages
Reviewed-by: sundar
This commit is contained in:
Jonathan Gibbons
parent
10fca535db
commit
ea084baf94
12 changed files with 267 additions and 76 deletions
|
|
@ -0,0 +1,36 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2018, 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.
|
||||
*/
|
||||
|
||||
/**
|
||||
* This package provides the javadoc implementation of relevant
|
||||
* public API defined in {@link javax.tools}, which provides an
|
||||
* API alternative to invoking javadoc via the command line.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal.api;
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2007, 2017, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2007, 2018, 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
|
||||
|
|
@ -24,17 +24,18 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* This package contains classes that create and write HTML markup tags.
|
||||
* This package contains classes that create and write HTML markup tags.
|
||||
*
|
||||
* The primary low level classes are {@link HtmlTree} and subtypes
|
||||
* of {@code Content}. In addition, there are mid-level builders
|
||||
* like {@link TableHeader} and {@link Table} to help build more
|
||||
* complex HTML trees.
|
||||
* <p>The primary low level classes are
|
||||
* {@link jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree HtmlTree}
|
||||
* and other subtypes of {@code Content}. In addition, there are mid-level builders
|
||||
* like {@link jdk.javadoc.internal.doclets.formats.html.markup.TableHeader TableHeader}
|
||||
* and {@link jdk.javadoc.internal.doclets.formats.html.markup.Table Table}
|
||||
* to help build more complex HTML trees.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
|
||||
package jdk.javadoc.internal.doclets.formats.html.markup;
|
||||
|
|
|
|||
|
|
@ -0,0 +1,39 @@
|
|||
/*
|
||||
* Copyright (c) 2018, 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 set of low-level file-formats, to be used in conjunction with
|
||||
* the {@link jdk.javadoc.internal.doclets.toolkit doclets.toolkit} API.
|
||||
*
|
||||
* <p>Currently, only {@link jdk.javadoc.internal.doclets.formats.html HTML}
|
||||
* format is supported.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal.doclets.formats;
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2018, 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
|
||||
|
|
@ -24,10 +24,25 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
<p><b>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.</b>
|
||||
* Doclets provide the user-selectable backends for processing the
|
||||
* documentation comnments in Java source code.
|
||||
*
|
||||
* <p>Doclets are implementations of the {@link jdk.javadoc.doclet Doclet API}.</p>
|
||||
*
|
||||
* <p>Currently, there is only one supported doclet, the
|
||||
* {@link jdk.javadoc.internal.doclets.formats.html.HtmlDoclet HtmlDoclet},
|
||||
* for writing API documentation in HTML. Nevertheless, in order to
|
||||
* separate the high-level code for the general content of each page
|
||||
* from the low-level details of how to write such content, the code is
|
||||
* organized in two sections: a format-neutral
|
||||
* {@link jdk.javadoc.internal.doclets.toolkit toolkit API},
|
||||
* and a specific {@link jdk.javadoc.internal.doclets.formats format},
|
||||
* such as {@link jdk.javadoc.internal.doclets.formats.html HTML format}.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
|
||||
package jdk.javadoc.internal.doclets;
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2018, 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
|
||||
|
|
@ -24,17 +24,17 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
This doclet-independent package has a set of classes and
|
||||
interfaces that are the building blocks for doclets. They
|
||||
define the basic structure of doclets and make doclet
|
||||
writing much easier because they provide the content generation
|
||||
code to be shared among different doclets. Builders only provide
|
||||
the structure and content of API documentation.
|
||||
They will not provide any style markup.
|
||||
|
||||
<p><b>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.</b>
|
||||
*/
|
||||
* This doclet-independent package has a set of classes and
|
||||
* interfaces that are the building blocks for doclets. They
|
||||
* define the basic structure of doclets and make doclet
|
||||
* writing much easier because they provide the content generation
|
||||
* code to be shared among different doclets. Builders only provide
|
||||
* the structure and content of API documentation.
|
||||
* They do not directly provide any style markup.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal.doclets.toolkit.builders;
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2018, 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
|
||||
|
|
@ -24,29 +24,28 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
This package has classes used to generate Javadoc tag documentation.
|
||||
Doclets no longer have to implement its own version of standard tags
|
||||
such as @param and @throws. This is the single, doclet
|
||||
implementation of each standard tag that is shared by all
|
||||
doclets. Each doclet must have a taglet writer that takes a taglet
|
||||
as input and writes doclet-dependent output. The taglet itself will
|
||||
do the tag processing. For example, suppose we are outputing
|
||||
@throws tags. The taglet would:
|
||||
<ul>
|
||||
<li> Retrieve the list of throws tags to be documented.
|
||||
<li> Replace {@inheritDoc} with the appropriate documentation.
|
||||
<li> Add throws documentation for exceptions that are declared in
|
||||
the signature of the method but
|
||||
not documented with the throws tags.
|
||||
</ul>
|
||||
After doing the steps above, the taglet would pass the information to
|
||||
the taglet writer for writing. The taglets are essentially builders for
|
||||
tags.
|
||||
|
||||
<p><b>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.</b>
|
||||
*/
|
||||
|
||||
* This package has classes used to generate output for Javadoc tags.
|
||||
*
|
||||
* <p>Doclets no longer have to implement their own version of standard tags
|
||||
* such as @param and @throws. Individual taglets provide
|
||||
* common processing, independent of the output format.
|
||||
* Each doclet must have a taglet writer that takes a taglet
|
||||
* as input and writes doclet-dependent output. The taglet itself will
|
||||
* do the tag processing. For example, suppose we are outputing
|
||||
* @throws tags. The taglet would:
|
||||
* <ul>
|
||||
* <li> Retrieve the list of throws tags to be documented.
|
||||
* <li> Replace {@inheritDoc} with the appropriate documentation.
|
||||
* <li> Add throws documentation for exceptions that are declared in
|
||||
* the signature of the method but not documented with the throws tags.
|
||||
* </ul>
|
||||
* After doing the steps above, the taglet would pass the information to
|
||||
* the taglet writer for writing. The taglets are essentially builders for
|
||||
* tags.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal.doclets.toolkit.taglets;
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2018, 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
|
||||
|
|
@ -33,14 +33,14 @@ import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
|
|||
import jdk.javadoc.internal.doclets.toolkit.Content;
|
||||
|
||||
/**
|
||||
* Encapsulates information about a link.
|
||||
* Encapsulates information about a link.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*
|
||||
* @author Jamie Ho
|
||||
* @author Jamie Ho
|
||||
*/
|
||||
public abstract class LinkInfo {
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2018, 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
|
||||
|
|
@ -26,7 +26,7 @@
|
|||
package jdk.javadoc.internal.doclets.toolkit.util.links;
|
||||
|
||||
/**
|
||||
* Stores output of a link.
|
||||
* Stores output of a link.
|
||||
*
|
||||
* <p><b>This is NOT part of any supported API.
|
||||
* If you write code that depends on this, you do so at your own risk.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2018, 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
|
||||
|
|
@ -24,12 +24,11 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
Provides a factory for constructing links.
|
||||
|
||||
<p><b>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.</b>
|
||||
*/
|
||||
|
||||
* Provides a factory for constructing links.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal.doclets.toolkit.util.links;
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2018, 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
|
||||
|
|
@ -24,13 +24,12 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
This package has utility classes that perform common services required
|
||||
for API documentation generation.
|
||||
|
||||
<p><b>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.</b>
|
||||
*/
|
||||
|
||||
* This package has utility classes that perform common services required
|
||||
* for API documentation generation.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal.doclets.toolkit.util;
|
||||
|
|
|
|||
|
|
@ -0,0 +1,54 @@
|
|||
/*
|
||||
* Copyright (c) 2018, 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.
|
||||
*
|
||||
* <p>Internally, javadoc is composed of two primary parts:
|
||||
* the {@link jdk.javadoc.internal.tool tool}, and a series of
|
||||
* {@link jdk.javadoc.internal.doclets doclets}.
|
||||
*
|
||||
* The tool provides a common infrastructure for command-line processing,
|
||||
* and for reading the documentation comments in Java source files,
|
||||
* while doclets provide a user-selectable backend for determining
|
||||
* how to process the documentation comments.
|
||||
*
|
||||
* <p><em>Historical Note:</em> Prior to the introduction of the
|
||||
* {@link javax.lang.model Language Model API} in JDK 6, it was
|
||||
* not unusual to use the {@link com.sun.javadoc} API as a
|
||||
* modeling API. But the Language Model API, and associated
|
||||
* {@link javax.annotation.processing Annotation Processing API}
|
||||
* provided a better way to model programs, and in JDK 9,
|
||||
* javadoc itself was converted to using the Language Model API,
|
||||
* with the {@code com.sun.javadoc API} being deprecated for
|
||||
* eventual removal.
|
||||
* </p>
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal;
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
/*
|
||||
* Copyright (c) 2018, 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.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Provides the front end for the javadoc tool.
|
||||
*
|
||||
* <p>The main entry points are in {@link jdk.javadoc.internal.tool.Main}
|
||||
* which calls the (poorly-named) {@link jdk.javadoc.internal.tool.Start}
|
||||
* which provides the overall functionality of the tool.
|
||||
*
|
||||
* <p>The classes provide a framework for processing command-line options
|
||||
* and determining the set of elements (modules, packages, types and members)
|
||||
* to be documented.
|
||||
*
|
||||
* <p>The classes also provide the means to use the javac front end to read
|
||||
* source files, including the documentation comments.
|
||||
*
|
||||
* <p>Finally, once the appropriate files have been read, the classes invoke
|
||||
* the selected doclet to process those files, typically to generate API
|
||||
* documentation.
|
||||
*
|
||||
* <p><b>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.</b>
|
||||
*/
|
||||
package jdk.javadoc.internal.tool;
|
||||
Loading…
Add table
Add a link
Reference in a new issue