stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8164316: Refine the Doclet APIs

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Kumar Srinivasan 2016-11-24 20:48:52 -08:00
parent 54244b5e6d
commit f4c9d73b3e
42 changed files with 1079 additions and 789 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
View File

@ -25,7 +25,7 @@
package jdk.javadoc.doclet;
import java.util.ListIterator;
import java.util.List;
import java.util.Locale;
import java.util.Set;
@ -67,7 +67,7 @@ public interface Doclet {
* @param locale the locale to be used
* @param reporter the reporter to be used
*/
public void init(Locale locale, Reporter reporter);
void init(Locale locale, Reporter reporter);
/**
* Returns a name identifying the doclet. A name is a simple identifier
@ -76,14 +76,14 @@ public interface Doclet {
*
* @return name of the Doclet
*/
public abstract String getName();
String getName();
/**
* Returns all the supported options.
*
* @return a set containing all the supported options, an empty set if none
*/
public Set<Option> getSupportedOptions();
Set<? extends Option> getSupportedOptions();
/**
* Returns the version of the Java Programming Language supported
@ -92,7 +92,7 @@ public interface Doclet {
* @return the language version supported by this doclet, usually
* the latest version
*/
public SourceVersion getSupportedSourceVersion();
SourceVersion getSupportedSourceVersion();
/**
* The entry point of the doclet. Further processing will commence as
@ -101,7 +101,7 @@ public interface Doclet {
* @param environment from which essential information can be extracted
* @return true on success
*/
public boolean run(DocletEnvironment environment);
boolean run(DocletEnvironment environment);
/**
* An encapsulation of option name, aliases, parameters and descriptions
@ -128,10 +128,12 @@ public interface Doclet {
Option.Kind getKind();
/**
* Returns the option name. For instance for option "-group", will return "group"
* @return name of the option, if set, otherwise an empty String
* Returns the list of names that may be used to identify the option. For instance, the
* list could be {@code ["-classpath", "--class-path"]} for the
* option "-classpath", with an alias "--class-path".
* @return the names of the option
*/
String getName();
List<String> getNames();
/**
* Returns the parameters of the option. For instance "name &lt;p1&gt;:&lt;p2&gt;.."
@ -139,21 +141,14 @@ public interface Doclet {
*/
String getParameters();
/**
* Checks if the given option name is handled by this option.
* @param option the option name with or without the leading "-"
* @return true if same
*/
boolean matches(String option);
/**
* Processes the option and arguments as needed. This method will
* be invoked if the given option name matches the option.
* @param option the option
* @param arguments a ListIterator encapsulating the arguments
* @param arguments a list encapsulating the arguments
* @return true if operation succeeded, false otherwise
*/
boolean process(String option, ListIterator<String> arguments);
boolean process(String option, List<String> arguments);
/**
* The kind of an option.

71
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
View File

@ -25,17 +25,15 @@
package jdk.javadoc.doclet;
import java.util.List;
import java.util.Set;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.Elements;
import javax.lang.model.util.Types;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileObject.Kind;
import com.sun.source.util.DocTrees;
@ -48,29 +46,23 @@ import com.sun.source.util.DocTrees;
* @since 9
*/
public interface DocletEnvironment {
/**
* Returns the <a href="package-summary.html#included">included</a>
* modules.
*
* @return a set of included module elements
*/
Set<ModuleElement> getIncludedModuleElements();
/**
* Returns the <a href="package-summary.html#included">included</a>
* annotation types, classes, interfaces and enums in all packages.
* Returns the elements <a href="package-summary.html#specified">specified</a>
* when the tool is invoked.
*
* @return a set of included type elements
* @return the set of specified elements
*/
Set<TypeElement> getIncludedTypeElements();
Set<? extends Element> getSpecifiedElements();
/**
* Returns the <a href="package-summary.html#included">included</a>
* packages.
* Returns the module, package and type elements that should be
* <a href="package-summary.html#included">included</a> in the
* documentation.
*
* @return a set of included package elements
* @return the set of included elements
*/
Set<PackageElement> getIncludedPackageElements();
Set<? extends Element> getIncludedElements();
/**
* Returns an instance of the {@code DocTrees} utility class.
@ -90,25 +82,6 @@ public interface DocletEnvironment {
*/
Elements getElementUtils();
/**
* Returns the <a href="package-summary.html#included">selected</a>
* elements that can be documented.
*
* @param elements those that need to be checked
* @return elements selected, an empty list if none
*/
List<Element> getSelectedElements(List<? extends Element> elements);
/**
* Returns the elements <a href="package-summary.html#specified">specified</a>
* on the command line, usually module elements, package elements and type elements.
* If {@code -subpackages} and {@code -exclude} options
* are used, return all the non-excluded packages.
*
* @return elements specified on the command line.
*/
Set<Element> getSpecifiedElements();
/**
* Returns an instance of the {@code Types} utility class.
* This class provides methods for operating on
@ -119,13 +92,23 @@ public interface DocletEnvironment {
Types getTypeUtils();
/**
* Indicates if an element is <a href="package-summary.html#included">included</a>.
* Returns true if an element should be
* <a href="package-summary.html#included">included</a> in the
* documentation.
*
* @param e the Element in question
* @param e the element
* @return true if included, false otherwise
*/
boolean isIncluded(Element e);
/**
* Returns true if the element is <a href="package-summary.html#selected">selected</a>.
*
* @param e the element
* @return true if selected, false otherwise
*/
boolean isSelected(Element e);
/**
* Returns the file manager used to read and write files.
*
@ -145,7 +128,15 @@ public interface DocletEnvironment {
*
* @return the required level of module documentation
*/
public ModuleMode getModuleMode();
ModuleMode getModuleMode();
/**
* Returns the file kind of a type element.
*
* @param type the type element
* @return the file kind
*/
Kind getFileKind(TypeElement type);
enum ModuleMode {
/** Indicate API level documentation is required */

324
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java
View File

@ -48,65 +48,98 @@
* <pre>
* public boolean <b>run</b>(DocletEnvironment environment)
* </pre>
* The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the environment that the
* doclet will be initialized with. From this environment all other information can be
* extracted, in the form of {@link javax.lang.model} elements. One can further use the
* APIs and utilities described by {@link javax.lang.model} to query Elements and Types.
* The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the
* environment that the doclet will be initialized with. From this environment
* all other information can be extracted, in the form of
* {@link javax.lang.model.element.Element elements}. One can further use the APIs and utilities
* described by {@link javax.lang.model Language Model API} to query Elements and Types.
* <p>
*
* <a name="terminology"></a>
* <h3>Terminology</h3>
*
* <a name="specified"></a>
* Module, package and source file names can be provided as parameters to the
* javadoc tool -- these are called the <em>specified</em> set containing
* module elements, package elements and type elements.
* <p>
* Javadoc <em>selection control</em> can be specified with
* {@code --show-members:value}, {@code --showtypes:value}, where value can be one of
* the following:
* <ul>
* <li> public -- considers only public elements
* <li> protected -- considers public and protected elements
* <li> package -- considers public, protected and package private elements
* <li> private -- considers all elements
* </ul>
* <dl>
* <dt><a name="selected"></a>Selected</dt>
* <dd>An element is considered to be <em>selected</em>, if the
* <em>selection controls</em> <a href="#options">allow</a> it
* to be documented. (Note that synthetic elements are never
* selected.)
* </dd>
*
* The {@code --show-package:value} where a value of "exported" or "all" can be used to
* consider only exported packages or all packages within a module.
* <dt><a name="specified"></a>Specified</dt>
* <dd>The set of elements specified by the user are considered to be <em>specified
* elements</em>. Specified elements provide the starting points
* for determining the <em>included elements</em> to be documented.
* </dd>
*
* <dt><a name="included"></a>Included</dt>
* <dd>An element is considered to be <em>included</em>, if it is
* <em>specified</em> if it contains a <em>specified</em> element,
* or it is enclosed in a <em>specified</em> element, and is <em>selected</em>.
* Included elements will be documented.
* </dd>
*
* </dl>
* <p>
* The {@code --expand-requires:value}, expands the "requires" directives of a
* module declaration, to create a module set to considered for documentation
* <a name="options"></a>
* <h3>Options</h3>
* Javadoc <em>selection control</em> can be specified with these options
* as follows:
* <ul>
* <li> public -- follows and expands all "requires public" edges in the module graph
* <li> all -- follows and expands all "requires" edges in the module graph.
* By default, only the specified modules will be considered, without expansion
* of the module dependencies.
* <li>{@code --show-members:value} and {@code --show-types:value} can
* be used to filter the members, with the following values:
* <ul>
* <li> public -- considers only public elements
* <li> protected -- considers public and protected elements
* <li> package -- considers public, protected and package private elements
* <li> private -- considers all elements
* </ul>
*
* <li>{@code --show-packages:value} "exported" or "all" can be used
* to consider only exported packages or all packages within a module.
*
* <li>{@code --show-module-contents:value} can be used to specify the level at
* module declarations could be documented. A value of "api" indicates API
* level documentation, and "all" indicates detailed documentation.
* </ul>
* The following options can be used to specify the elements to be documented:
* <ul>
* <li>{@code --module} documents the specified modules.
*
* <li>{@code --expand-requires:value} expand the set of modules to be documented
* by including some or all of the modules dependencies. The value may be
* one of:
* <ul>
* <li> public -- each module specified explicitly on the command line is
* expanded to include the closure of its transitive dependencies
* <li> all -- each module specified explicitly on the command line
* is expanded to include the closure of its transitive dependencies,
* and also all of its direct dependencies
* </ul>
* By default, only the specified modules will be considered, without expansion
* of the module dependencies.
*
* <li>{@code packagenames} can be used to specify packages.
* <li>{@code -subpackages} can be used to recursively load packages.
* <li>{@code -exclude} can be used exclude package directories.
* <li>{@code sourcefilenames} can be used to specify source file names.
* </ul>
* <a name="included"></a>
* All of the above are used to select the elements, to produce the
* <em>included</em> or the <em>selected</em> set.
* <p>
* {@code --show-module-contents:value} can be used to specify the level at
* module declarations could be documented, a value of "api" indicates API
* level documentation, and "all" indicates detailed documentation.
* <p>
* <a name="legacy-interactions"></a>
* <h4>Interactions with older options.</h4>
*
* The new --show-* options provide a more detailed replacement for the older
* options -public, -protected, -package, -private. Alternatively, the older
* options can continue to be used as shorter forms for combinations of the
* new options, as described below:
* The new {@code --show-*} options provide a more detailed replacement
* for the older options -public, -protected, -package, -private.
* Alternatively, the older options can continue to be used as shorter
* forms for combinations of the new options, as described below:
<table style="font-family: monospace" border=1>
<caption>Short form options mapping</caption>
<tr><th>Older option<th colspan="5">Equivalent to these values with the new option
<tr><th><th>--show-members<th>--show-types<th>--show-packages<th>--show-module-contents
<tr><td>-public<td>public<td>public<td>exported<td>api
<tr><td>-protected<td>protected<td>protected<td>exported<td>api
<tr><td>-package<td>package<td>package<td>all<td>all
<tr><td>-private<td>private<td>private<td>all<td>all
<tr><th><th>{@code --show-members}<th>{@code --show-types}<th>{@code --show-packages}<th>{@code --show-module-contents}
<tr><td>{@code -public}<td>public<td>public<td>exported<td>api
<tr><td>{@code -protected}<td>protected<td>protected<td>exported<td>api
<tr><td>{@code -package}<td>package<td>package<td>all<td>all
<tr><td>{@code -private}<td>private<td>private<td>all<td>all
</table>
* <p>
* <a name="qualified"></a>
@ -119,127 +152,120 @@
* <h3>Example</h3>
*
* The following is an example doclet that displays information of a class
* and its members, supporting an option "someoption".
* and its members, supporting an option.
* <pre>
* import com.sun.source.doctree.DocCommentTree;
* import com.sun.source.util.DocTrees;
* import java.io.IOException;
* import java.util.Collections;
* import java.util.Set;
* import javax.lang.model.SourceVersion;
* import javax.lang.model.element.Element;
* import javax.lang.model.element.TypeElement;
* import jdk.javadoc.doclet.*;
*
* // note imports deleted for clarity
* public class Example implements Doclet {
* Reporter reporter;
* &#64;Override
* public void init(Locale locale, Reporter reporter) {
* reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
* this.reporter = reporter;
* }
*
* &#64;Override
* public void init(Locale locale, Reporter reporter) {
* return;
* }
* public void printElement(DocTrees trees, Element e) {
* DocCommentTree docCommentTree = trees.getDocCommentTree(e);
* if (docCommentTree != null) {
* System.out.println("Element (" + e.getKind() + ": "
* + e + ") has the following comments:");
* System.out.println("Entire body: " + docCommentTree.getFullBody());
* System.out.println("Block tags: " + docCommentTree.getBlockTags());
* }
* }
*
* &#64;Override
* public boolean run(DocletEnvironment docEnv) {
* // cache the DocTrees utility class to access DocComments
* DocTrees docTrees = docEnv.getDocTrees();
* &#64;Override
* public boolean run(DocletEnvironment docEnv) {
* reporter.print(Kind.NOTE, "overviewfile: " + overviewfile);
* // get the DocTrees utility class to access document comments
* DocTrees docTrees = docEnv.getDocTrees();
*
* // location of an element in the same directory as overview.html
* try {
* Element barElement = null;
* for (Element e : docEnv.getIncludedClasses()) {
* if (e.getSimpleName().toString().equals("FooBar")) {
* barElement = e;
* }
* }
* DocCommentTree docCommentTree =
* docTrees.getDocCommentTree(barElement, "overview.html");
* if (docCommentTree != null) {
* System.out.println("Overview html: " +
* docCommentTree.getFullBody());
* }
* } catch (IOException missing) {
* System.err.println("No overview.html found.");
* }
* // location of an element in the same directory as overview.html
* try {
* Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
* DocCommentTree docCommentTree
* = docTrees.getDocCommentTree(e, overviewfile);
* if (docCommentTree != null) {
* System.out.println("Overview html: " + docCommentTree.getFullBody());
* }
* } catch (IOException missing) {
* reporter.print(Kind.ERROR, "No overview.html found.");
* }
*
* for (TypeElement t : docEnv.getIncludedClasses()) {
* System.out.println(t.getKind() + ":" + t);
* for (Element e : t.getEnclosedElements()) {
* DocCommentTree docCommentTree = docTrees.getDocCommentTree(e);
* if (docCommentTree != null) {
* System.out.println("Element (" + e.getKind() + ": " +
* e + ") has the following comments:");
* System.out.println("Entire body: " + docCommentTree.getFullBody());
* System.out.println("Block tags: " + docCommentTree.getBlockTags());
* } else {
* System.out.println("no comment.");
* }
* }
* }
* return true;
* }
* for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
* System.out.println(t.getKind() + ":" + t);
* for (Element e : t.getEnclosedElements()) {
* printElement(docTrees, e);
* }
* }
* return true;
* }
*
* &#64;Override
* public String getName() {
* return "Example";
* }
* &#64;Override
* public String getName() {
* return "Example";
* }
*
* private String someOption;
* private String overviewfile;
*
* &#64;Override
* public Set&lt;Option&gt; getSupportedOptions() {
* Option[] options = {
* new Option() {
* public int getArgumentCount() {
* return 1;
* }
* public String getDescription() {
* return "someoption";
* }
* public Option.Kind getKind() {
* return Option.Kind.STANDARD;
* }
* public String getName() {
* return "someoption";
* }
* public String getParameters() {
* return "url";
* }
* public boolean matches(String option) {
* String opt = option.startsWith("-") ? option.substring(1) : option;
* return getName().equals(opt);
* }
* public boolean process(String option, ListIterator&lt;String&gt; arguments) {
* overviewpath = arguments.next();
* return true;
* }
* }
* };
* return new HashSet&lt;Option&gt;(Arrays.asList(options));
* }
* &#64;Override
* public Set&lt;? extends Option&gt; getSupportedOptions() {
* Option[] options = {
* new Option() {
* private final List&lt;String&gt; someOption = Arrays.asList(
* "-overviewfile",
* "--overview-file",
* "-o"
* );
*
* &#64;Override
* public SourceVersion getSupportedSourceVersion() {
* // support the latest release
* return SourceVersion.latest();
* }
* &#64;Override
* public int getArgumentCount() {
* return 1;
* }
*
* &#64;Override
* public String getDescription() {
* return "an option with aliases";
* }
*
* &#64;Override
* public Option.Kind getKind() {
* return Option.Kind.STANDARD;
* }
*
* &#64;Override
* public List&lt;String&gt; getNames() {
* return someOption;
* }
*
* &#64;Override
* public String getParameters() {
* return "file";
* }
*
* &#64;Override
* public boolean process(String opt, List&lt;String&gt; arguments) {
* overviewfile = arguments.get(0);
* return true;
* }
* }
* };
* return new HashSet&lt;&gt;(Arrays.asList(options));
* }
*
* &#64;Override
* public SourceVersion getSupportedSourceVersion() {
* // support the latest release
* return SourceVersion.latest();
* }
* }
* </pre>
* <p>
* This doclet when invoked with a command line, such as:
* This doclet can be invoked with a command line, such as:
* <pre>
* javadoc -doclet Example -sourcepath &lt;source-location&gt;
* </pre>
* will produce an output, such as:
* <pre>
* Overview.html: overview comments
* ...
* ...
* CLASS: SomeKlass
* .....
* Element (METHOD: main(java.lang.String...)) has the following comments:
* Entire body: The main entry point.
* Block tags: @param an array of Strings
* ...
* javadoc -doclet Example &#92;
* -overviewfile overview.html &#92;
* -sourcepath source-location &#92;
* source-location/Example.java
* </pre>
*
* <h3><a name="migration">Migration Guide</a></h3>

8
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java
View File

@ -54,13 +54,13 @@ public interface Taglet {
* @return true if this <code>Taglet</code>
* is an inline tag, false otherwise.
*/
public abstract boolean isInlineTag();
boolean isInlineTag();
/**
* Returns the name of the tag.
* @return the name of this custom tag.
*/
public abstract String getName();
String getName();
/**
* Given the {@link DocTree DocTree} representation of this custom
@ -69,7 +69,7 @@ public interface Taglet {
* @param tag the <code>Tag</code> representation of this custom tag.
* @return the string representation of this <code>Tag</code>.
*/
public abstract String toString(DocTree tag);
String toString(DocTree tag);
/**
* Given a List of {@link DocTree DocTrees} representing this custom
@ -79,7 +79,7 @@ public interface Taglet {
* @param tags the list of <code>DocTree</code>s representing this custom tag.
* @return the string representation of this <code>Tag</code>.
*/
public abstract String toString(List<? extends DocTree> tags);
String toString(List<? extends DocTree> tags);
/**
* The kind of location.

3
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
View File

@ -52,6 +52,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
/**
* Generate class usage information.
*
@ -178,7 +179,7 @@ public class ClassUseWriter extends SubWriterHolderWriter {
*/
public static void generate(ConfigurationImpl configuration, ClassTree classtree) throws DocFileIOException {
ClassUseMapper mapper = new ClassUseMapper(configuration, classtree);
for (TypeElement aClass : configuration.docEnv.getIncludedTypeElements()) {
for (TypeElement aClass : configuration.getIncludedTypeElements()) {
// If -nodeprecated option is set and the containing package is marked
// as deprecated, do not generate the class-use page. We will still generate
// the class-use page if the class is marked as deprecated but the containing

267
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java
View File

@ -288,83 +288,13 @@ public class ConfigurationImpl extends Configuration {
if (!generalValidOptions()) {
return false;
}
boolean helpfileSeen = false;
// otherwise look at our options
for (Doclet.Option opt : optionsProcessed) {
if (opt.matches("-helpfile")) {
if (nohelp == true) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-helpfile", "-nohelp"));
return false;
}
if (helpfileSeen) {
reporter.print(ERROR, getText("doclet.Option_reuse",
"-helpfile"));
return false;
}
helpfileSeen = true;
DocFile help = DocFile.createFileForInput(this, helpfile);
if (!help.exists()) {
reporter.print(ERROR, getText("doclet.File_not_found", helpfile));
return false;
}
} else if (opt.matches("-nohelp")) {
if (helpfileSeen) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-nohelp", "-helpfile"));
return false;
}
} else if (opt.matches("-xdocrootparent")) {
try {
URL ignored = new URL(docrootparent);
} catch (MalformedURLException e) {
reporter.print(ERROR, getText("doclet.MalformedURL", docrootparent));
return false;
}
} else if (opt.matches("-overview")) {
if (nooverview == true) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-overview", "-nooverview"));
return false;
}
} else if (opt.matches("-nooverview")) {
if (overviewpath != null) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-nooverview", "-overview"));
return false;
}
} else if (opt.matches("-splitindex")) {
if (createindex == false) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-splitindex", "-noindex"));
return false;
}
} else if (opt.matches("-noindex")) {
if (splitindex == true) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-noindex", "-splitindex"));
return false;
}
} else if (opt.matches("-xdoclint:")) {
String dopt = doclintOpts.get(opt);
if (dopt == null) {
continue;
}
if (dopt.contains("/")) {
reporter.print(ERROR, getText("doclet.Option_doclint_no_qualifiers"));
return false;
}
if (!DocLint.isValidOption(dopt)) {
reporter.print(ERROR, getText("doclet.Option_doclint_invalid_arg"));
return false;
}
} else if (opt.matches("-xdoclint/package:")) {
String dopt = doclintOpts.get(opt);
if (!DocLint.isValidOption(dopt)) {
reporter.print(ERROR, getText("doclet.Option_doclint_package_invalid_arg"));
return false;
}
}
// check if helpfile exists
if (!helpfile.isEmpty()) {
DocFile help = DocFile.createFileForInput(this, helpfile);
if (!help.exists()) {
reporter.print(ERROR, getText("doclet.File_not_found", helpfile));
return false;
}
}
return true;
}
@ -374,11 +304,10 @@ public class ConfigurationImpl extends Configuration {
if (!validateOptions()) {
return false;
}
if (!docEnv.getSpecifiedElements().isEmpty()) {
if (!getSpecifiedTypeElements().isEmpty()) {
Map<String, PackageElement> map = new HashMap<>();
PackageElement pkg;
List<TypeElement> classes = new ArrayList<>(docEnv.getIncludedTypeElements());
for (TypeElement aClass : classes) {
for (TypeElement aClass : getIncludedTypeElements()) {
pkg = utils.containingPackage(aClass);
if (!map.containsKey(utils.getPackageName(pkg))) {
map.put(utils.getPackageName(pkg), pkg);
@ -426,7 +355,7 @@ public class ConfigurationImpl extends Configuration {
if (showModules) {
topFile = DocPath.empty.resolve(DocPaths.moduleSummary(modules.first()));
} else if (packages.size() == 1 && packages.first().isUnnamed()) {
List<TypeElement> classes = new ArrayList<>(docEnv.getIncludedTypeElements());
List<TypeElement> classes = new ArrayList<>(getIncludedTypeElements());
if (!classes.isEmpty()) {
TypeElement te = getValidClass(classes);
topFile = DocPath.forClass(utils, te);
@ -450,7 +379,7 @@ public class ConfigurationImpl extends Configuration {
}
protected boolean checkForDeprecation(DocletEnvironment docEnv) {
for (TypeElement te : docEnv.getIncludedTypeElements()) {
for (TypeElement te : getIncludedTypeElements()) {
if (isGeneratedDoc(te)) {
return true;
}
@ -597,227 +526,245 @@ public class ConfigurationImpl extends Configuration {
Doclet.Option[] options = {
new Option(resources, "-bottom", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
bottom = args.next();
public boolean process(String opt, List<String> args) {
bottom = args.get(0);
return true;
}
},
new Option(resources, "-charset", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
charset = args.next();
public boolean process(String opt, List<String> args) {
charset = args.get(0);
return true;
}
},
new Option(resources, "-doctitle", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
doctitle = args.next();
public boolean process(String opt, List<String> args) {
doctitle = args.get(0);
return true;
}
},
new Option(resources, "-footer", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
footer = args.next();
public boolean process(String opt, List<String> args) {
footer = args.get(0);
return true;
}
},
new Option(resources, "-header", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
header = args.next();
public boolean process(String opt, List<String> args) {
header = args.get(0);
return true;
}
},
new Option(resources, "-helpfile", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
helpfile = args.next();
public boolean process(String opt, List<String> args) {
if (nohelp == true) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-helpfile", "-nohelp"));
return false;
}
if (!helpfile.isEmpty()) {
reporter.print(ERROR, getText("doclet.Option_reuse",
"-helpfile"));
return false;
}
helpfile = args.get(0);
return true;
}
},
new Option(resources, "-html4") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
htmlVersion = HtmlVersion.HTML4;
return true;
}
},
new Option(resources, "-html5") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
htmlVersion = HtmlVersion.HTML5;
return true;
}
},
new Option(resources, "-nohelp") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
nohelp = true;
if (!helpfile.isEmpty()) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-nohelp", "-helpfile"));
return false;
}
return true;
}
},
new Option(resources, "-nodeprecatedlist") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
nodeprecatedlist = true;
return true;
}
},
new Option(resources, "-noindex") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
createindex = false;
if (splitindex == true) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-noindex", "-splitindex"));
return false;
}
return true;
}
},
new Option(resources, "-nonavbar") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
nonavbar = true;
return true;
}
},
new Hidden(resources, "-nooverview") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
nooverview = true;
if (overviewpath != null) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-nooverview", "-overview"));
return false;
}
return true;
}
},
new Option(resources, "-notree") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
createtree = false;
return true;
}
},
new Option(resources, "-overview", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
overviewpath = args.next();
public boolean process(String opt, List<String> args) {
overviewpath = args.get(0);
if (nooverview == true) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-overview", "-nooverview"));
return false;
}
return true;
}
},
new Option(resources, "--frames") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
frames = true;
return true;
}
},
new Option(resources, "--no-frames") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
frames = false;
return true;
}
},
new Hidden(resources, "-packagesheader", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
packagesheader = args.next();
public boolean process(String opt, List<String> args) {
packagesheader = args.get(0);
return true;
}
},
new Option(resources, "-splitindex") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
splitindex = true;
if (createindex == false) {
reporter.print(ERROR, getText("doclet.Option_conflict",
"-splitindex", "-noindex"));
return false;
}
return true;
}
},
new Option(resources, "-stylesheetfile", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
stylesheetfile = args.next();
public boolean process(String opt, List<String> args) {
stylesheetfile = args.get(0);
return true;
}
},
new Option(resources, "-top", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
top = args.next();
public boolean process(String opt, List<String> args) {
top = args.get(0);
return true;
}
},
new Option(resources, "-use") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
classuse = true;
return true;
}
},
new Option(resources, "-windowtitle", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
windowtitle = args.next().replaceAll("\\<.*?>", "");
public boolean process(String opt, List<String> args) {
windowtitle = args.get(0).replaceAll("\\<.*?>", "");
return true;
}
},
new XOption(resources, "-Xdoclint") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
doclintOpts.put(this, DocLint.XMSGS_OPTION);
return true;
}
},
new XOption(resources, "-Xdocrootparent", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
docrootparent = args.next();
public boolean process(String opt, List<String> args) {
docrootparent = args.get(0);
try {
URL ignored = new URL(docrootparent);
} catch (MalformedURLException e) {
reporter.print(ERROR, getText("doclet.MalformedURL", docrootparent));
return false;
}
return true;
}
},
new XOption(resources, "doclet.usage.xdoclint-extended", "-Xdoclint:", 0) {
@Override
public boolean matches(String option) {
return option.toLowerCase().startsWith(getName().toLowerCase());
}
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
doclintOpts.put(this, opt.replace("-Xdoclint:", DocLint.XMSGS_CUSTOM_PREFIX));
public boolean process(String opt, List<String> args) {
String dopt = opt.replace("-Xdoclint:", DocLint.XMSGS_CUSTOM_PREFIX);
doclintOpts.put(this, dopt);
if (dopt.contains("/")) {
reporter.print(ERROR, getText("doclet.Option_doclint_no_qualifiers"));
return false;
}
if (!DocLint.isValidOption(dopt)) {
reporter.print(ERROR, getText("doclet.Option_doclint_invalid_arg"));
return false;
}
return true;
}
},
new XOption(resources, "doclet.usage.xdoclint-package", "-Xdoclint/package:", 0) {
@Override
public boolean matches(String option) {
return option.toLowerCase().startsWith(getName().toLowerCase());
}
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
doclintOpts.put(this, opt.replace("-Xdoclint/package:", DocLint.XCHECK_PACKAGE));
public boolean process(String opt, List<String> args) {
String dopt = opt.replace("-Xdoclint/package:", DocLint.XCHECK_PACKAGE);
doclintOpts.put(this, dopt);
if (!DocLint.isValidOption(dopt)) {
reporter.print(ERROR, getText("doclet.Option_doclint_package_invalid_arg"));
return false;
}
return true;
}
}

8
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
View File

@ -91,10 +91,11 @@ public class HtmlDoclet extends AbstractDoclet {
* Create the configuration instance.
* Override this method to use a different
* configuration.
* @return the configuration for this doclet
*
* @return the configuration
*/
@Override // defined by AbstractDoclet
public ConfigurationImpl configuration() {
public ConfigurationImpl getConfiguration() {
return configuration;
}
@ -166,8 +167,7 @@ public class HtmlDoclet extends AbstractDoclet {
IndexRedirectWriter.generate(configuration);
}
if (configuration.helpfile.length() == 0 &&
!configuration.nohelp) {
if (configuration.helpfile.isEmpty() && !configuration.nohelp) {
HelpWriter.generate(configuration);
}
// If a stylesheet file is not specified, copy the default stylesheet

4
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
View File

@ -826,8 +826,8 @@ public class HtmlDocletWriter extends HtmlDocWriter {
* @return a content tree for the link
*/
protected Content getNavLinkTree() {
List<PackageElement> packages = new ArrayList<>(configuration.getSpecifiedPackages());
DocPath docPath = packages.size() == 1 && configuration.getSpecifiedClasses().isEmpty()
List<PackageElement> packages = new ArrayList<>(configuration.getSpecifiedPackageElements());
DocPath docPath = packages.size() == 1 && configuration.getSpecifiedTypeElements().isEmpty()
? pathString(packages.get(0), DocPaths.PACKAGE_TREE)
: pathToRoot.resolve(DocPaths.OVERVIEW_TREE);
return HtmlTree.LI(getHyperLink(docPath, contents.treeLabel, "", ""));

6
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java
View File

@ -32,6 +32,7 @@ import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
@ -41,7 +42,6 @@ import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
/**
* Class to generate file for each module contents in the left-hand bottom
* frame. This will list all the Class Kinds in the module. A click on any
@ -78,9 +78,9 @@ public class ModuleFrameWriter extends HtmlDocletWriter {
public ModuleFrameWriter(ConfigurationImpl configuration, ModuleElement moduleElement) {
super(configuration, DocPaths.moduleTypeFrame(moduleElement));
this.mdle = moduleElement;
if (configuration.getSpecifiedPackages().isEmpty()) {
if (configuration.getSpecifiedPackageElements().isEmpty()) {
documentedClasses = new TreeSet<>(utils.makeGeneralPurposeComparator());
documentedClasses.addAll(configuration.docEnv.getIncludedTypeElements());
documentedClasses.addAll(configuration.getIncludedTypeElements());
}
}

6
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java
View File

@ -30,6 +30,7 @@ import java.util.*;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
@ -41,7 +42,6 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
/**
* Class to generate file for each package contents in the left-hand bottom
* frame. This will list all the Class Kinds in the package. A click on any
@ -82,9 +82,9 @@ public class PackageFrameWriter extends HtmlDocletWriter {
public PackageFrameWriter(ConfigurationImpl configuration, PackageElement packageElement) {
super(configuration, DocPath.forPackage(packageElement).resolve(DocPaths.PACKAGE_FRAME));
this.packageElement = packageElement;
if (configuration.getSpecifiedPackages().isEmpty()) {
if (configuration.getSpecifiedPackageElements().isEmpty()) {
documentedClasses = new TreeSet<>(utils.makeGeneralPurposeComparator());
documentedClasses.addAll(configuration.docEnv.getIncludedTypeElements());
documentedClasses.addAll(configuration.getIncludedTypeElements());
}
}

2
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java
View File

@ -66,7 +66,7 @@ public class SerializedFormWriterImpl extends SubWriterHolderWriter
*/
public SerializedFormWriterImpl(ConfigurationImpl configuration) {
super(configuration, DocPaths.SERIALIZED_FORM);
visibleClasses = configuration.docEnv.getIncludedTypeElements();
visibleClasses = configuration.getIncludedTypeElements();
}
/**

4
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java
View File

@ -115,13 +115,13 @@ public class SourceToHTMLConverter {
if (docEnv == null || outputdir == null) {
return;
}
for (PackageElement pkg : configuration.getSpecifiedPackages()) {
for (PackageElement pkg : configuration.getSpecifiedPackageElements()) {
// If -nodeprecated option is set and the package is marked as deprecated,
// do not convert the package files to HTML.
if (!(configuration.nodeprecated && utils.isDeprecated(pkg)))
convertPackage(pkg, outputdir);
}
for (TypeElement te : configuration.getSpecifiedClasses()) {
for (TypeElement te : configuration.getSpecifiedTypeElements()) {
// If -nodeprecated option is set and the class is marked as deprecated
// or the containing package is deprecated, do not convert the
// package files to HTML.

11
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java
View File

@ -99,8 +99,8 @@ public abstract class AbstractDoclet implements Doclet {
*/
@Override
public boolean run(DocletEnvironment docEnv) {
configuration = configuration();
configuration.docEnv = docEnv;
configuration = getConfiguration();
configuration.initConfiguration(docEnv);
configuration.cmtUtils = new CommentUtils(configuration);
configuration.utils = new Utils(configuration);
utils = configuration.utils;
@ -171,13 +171,12 @@ public abstract class AbstractDoclet implements Doclet {
return SourceVersion.RELEASE_9;
}
/**
* Create the configuration instance and returns it.
*
* @return the configuration of the doclet.
*/
public abstract Configuration configuration();
public abstract Configuration getConfiguration();
/**
* Start the generation of files. Call generate methods in the individual
@ -189,7 +188,7 @@ public abstract class AbstractDoclet implements Doclet {
* @throws DocletException if there is a problem while generating the documentation
*/
private void startGeneration(DocletEnvironment docEnv) throws DocletException {
if (docEnv.getIncludedTypeElements().isEmpty()) {
if (configuration.getIncludedTypeElements().isEmpty()) {
messages.error("doclet.No_Public_Classes_To_Document");
return;
}
@ -263,7 +262,7 @@ public abstract class AbstractDoclet implements Doclet {
throws DocletException {
generateClassFiles(classtree);
SortedSet<PackageElement> packages = new TreeSet<>(utils.makePackageComparator());
packages.addAll(configuration.getSpecifiedPackages());
packages.addAll(configuration.getSpecifiedPackageElements());
configuration.modulePackages.values().stream().forEach(pset -> {
packages.addAll(pset);
});

293
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java
View File

@ -33,10 +33,13 @@ import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import javax.lang.model.util.SimpleElementVisitor9;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileObject;
import com.sun.source.util.DocTreePath;
import com.sun.tools.javac.util.DefinedBy;
import com.sun.tools.javac.util.DefinedBy.Api;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.doclet.Reporter;
@ -96,7 +99,7 @@ public abstract class Configuration {
/**
* The path to Taglets
*/
public String tagletpath = "";
public String tagletpath = null;
/**
* This is true if option "-serialwarn" is used. Defualt value is false to
@ -312,9 +315,7 @@ public abstract class Configuration {
*/
public SortedSet<PackageElement> packages = null;
protected final List<Doclet.Option> optionsProcessed;
public final OverviewElement overviewElement;
public OverviewElement overviewElement;
// The following three fields provide caches for use by all instances of VisibleMemberMap.
public final Map<TypeElement, List<Element>> propertiesCache = new HashMap<>();
@ -336,16 +337,34 @@ public abstract class Configuration {
protected static final String sharedResourceBundleName =
"jdk.javadoc.internal.doclets.toolkit.resources.doclets";
/**
* Constructor. Constructs the message retriever with resource file.
* Constructs the configurations needed by the doclet.
*/
public Configuration() {
excludedDocFileDirs = new HashSet<>();
excludedQualifiers = new HashSet<>();
setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
metakeywords = new MetaKeywords(this);
optionsProcessed = new ArrayList<>();
groups = new ArrayList<>(0);
}
private boolean initialized = false;
protected void initConfiguration(DocletEnvironment docEnv) {
if (initialized) {
throw new IllegalStateException("configuration previously initialized");
}
initialized = true;
this.docEnv = docEnv;
overviewElement = new OverviewElement(docEnv);
Splitter specifiedSplitter = new Splitter(docEnv, false);
specifiedModuleElements = Collections.unmodifiableSet(specifiedSplitter.mset);
specifiedPackageElements = Collections.unmodifiableSet(specifiedSplitter.pset);
specifiedTypeElements = Collections.unmodifiableSet(specifiedSplitter.tset);
Splitter includedSplitter = new Splitter(docEnv, true);
includedModuleElements = Collections.unmodifiableSet(includedSplitter.mset);
includedPackageElements = Collections.unmodifiableSet(includedSplitter.pset);
includedTypeElements = Collections.unmodifiableSet(includedSplitter.tset);
}
/**
@ -364,10 +383,40 @@ public abstract class Configuration {
return this.reporter;
}
private Set<ModuleElement> specifiedModuleElements;
public Set<ModuleElement> getSpecifiedModuleElements() {
return specifiedModuleElements;
}
private Set<PackageElement> specifiedPackageElements;
public Set<PackageElement> getSpecifiedPackageElements() {
return specifiedPackageElements;
}
private Set<TypeElement> specifiedTypeElements;
public Set<TypeElement> getSpecifiedTypeElements() {
return specifiedTypeElements;
}
private Set<ModuleElement> includedModuleElements;
public Set<ModuleElement> getIncludedModuleElements() {
return includedModuleElements;
}
private Set<PackageElement> includedPackageElements;
public Set<PackageElement> getIncludedPackageElements() {
return includedPackageElements;
}
private Set<TypeElement> includedTypeElements;
public Set<TypeElement> getIncludedTypeElements() {
return includedTypeElements;
}
private void initModules() {
// Build the modules structure used by the doclet
modules = new TreeSet<>(utils.makeModuleComparator());
modules.addAll(getSpecifiedModules());
modules.addAll(getSpecifiedModuleElements());
modulePackages = new TreeMap<>(utils.makeModuleComparator());
for (PackageElement p: packages) {
@ -379,7 +428,7 @@ public abstract class Configuration {
}
}
for (PackageElement p: docEnv.getIncludedPackageElements()) {
for (PackageElement p: getIncludedPackageElements()) {
ModuleElement mdle = docEnv.getElementUtils().getModuleOf(p);
if (mdle != null && !mdle.isUnnamed()) {
Set<PackageElement> s = modulePackages
@ -398,7 +447,7 @@ public abstract class Configuration {
private void initPackages() {
packages = new TreeSet<>(utils.makePackageComparator());
// add all the included packages
packages.addAll(docEnv.getIncludedPackageElements());
packages.addAll(includedPackageElements);
}
public Set<Doclet.Option> getSupportedOptions() {
@ -406,165 +455,145 @@ public abstract class Configuration {
Doclet.Option[] options = {
new Option(resources, "-author") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
showauthor = true;
return true;
}
},
new Option(resources, "-d", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
destDirName = addTrailingFileSep(args.next());
public boolean process(String opt, List<String> args) {
destDirName = addTrailingFileSep(args.get(0));
return true;
}
},
new Option(resources, "-docencoding", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
docencoding = args.next();
public boolean process(String opt, List<String> args) {
docencoding = args.get(0);
return true;
}
},
new Option(resources, "-docfilessubdirs") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
copydocfilesubdirs = true;
return true;
}
},
new Hidden(resources, "-encoding", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
encoding = args.next();
public boolean process(String opt, List<String> args) {
encoding = args.get(0);
return true;
}
},
new Option(resources, "-excludedocfilessubdir", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
addToSet(excludedDocFileDirs, args.next());
public boolean process(String opt, List<String> args) {
addToSet(excludedDocFileDirs, args.get(0));
return true;
}
},
new Option(resources, "-group", 2) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
groups.add(new GroupContainer(args.next(), args.next()));
public boolean process(String opt, List<String> args) {
groups.add(new GroupContainer(args.get(0), args.get(1)));
return true;
}
},
new Hidden(resources, "-javafx") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
javafx = true;
return true;
}
},
new Option(resources, "-keywords") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
keywords = true;
return true;
}
},
new Option(resources, "-link", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
urlForLink = args.next();
public boolean process(String opt, List<String> args) {
urlForLink = args.get(0);
pkglistUrlForLink = urlForLink;
return true;
}
},
new Option(resources, "-linksource") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
linksource = true;
return true;
}
},
new Option(resources, "-linkoffline", 2) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
urlForLinkOffline = args.next();
pkglistUrlForLinkOffline = args.next();
public boolean process(String opt, List<String> args) {
urlForLinkOffline = args.get(0);
pkglistUrlForLinkOffline = args.get(1);
return true;
}
},
new Option(resources, "-nocomment") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
nocomment = true;
return true;
}
},
new Option(resources, "-nodeprecated") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
nodeprecated = true;
return true;
}
},
new Option(resources, "-nosince") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
nosince = true;
return true;
}
},
new Option(resources, "-notimestamp") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
notimestamp = true;
return true;
}
},
new Option(resources, "-noqualifier", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
addToSet(excludedQualifiers, args.next());
public boolean process(String opt, List<String> args) {
addToSet(excludedQualifiers, args.get(0));
return true;
}
},
new Hidden(resources, "-quiet") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
quiet = true;
return true;
}
},
new Option(resources, "-serialwarn") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
serialwarn = true;
return true;
}
},
new Option(resources, "-sourcetab", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
linksource = true;
try {
setTabWidth(Integer.parseInt(args.next()));
setTabWidth(Integer.parseInt(args.get(0)));
} catch (NumberFormatException e) {
//Set to -1 so that warning will be printed
//to indicate what is valid argument.
@ -579,45 +608,41 @@ public abstract class Configuration {
},
new Option(resources, "-tag", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
ArrayList<String> list = new ArrayList<>();
list.add(opt);
list.add(args.next());
list.add(args.get(0));
customTagStrs.add(list);
return true;
}
},
new Option(resources, "-taglet", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
ArrayList<String> list = new ArrayList<>();
list.add(opt);
list.add(args.next());
list.add(args.get(0));
customTagStrs.add(list);
return true;
}
},
new Option(resources, "-tagletpath", 1) {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
tagletpath = args.next();
public boolean process(String opt, List<String> args) {
tagletpath = args.get(0);
return true;
}
},
new Option(resources, "-version") {
@Override
public boolean process(String opt, ListIterator<String> args) {
optionsProcessed.add(this);
public boolean process(String opt, List<String> args) {
showversion = true;
return true;
}
},
new Hidden(resources, "--dump-on-error") {
@Override
public boolean process(String opt, ListIterator<String> args) {
public boolean process(String opt, List<String> args) {
dumpOnError = true;
return true;
}
@ -643,7 +668,7 @@ public abstract class Configuration {
if (docencoding == null) {
docencoding = encoding;
}
typeElementCatalog = new TypeElementCatalog(docEnv.getIncludedTypeElements(), this);
typeElementCatalog = new TypeElementCatalog(includedTypeElements, this);
initTagletManager(customTagStrs);
groups.stream().forEach((grp) -> {
group.checkPackageGroups(grp.value1, grp.value2);
@ -798,25 +823,19 @@ public abstract class Configuration {
}
/**
*
* This checks for the validity of the options used by the user.
* This works exactly like DocErrorReporter. This will validate the options which are shared
* by our doclets. For example, this method will flag an error using
* the DocErrorReporter if user has used "-nohelp" and "-helpfile" option
* together.
* As of this writing, this checks only docencoding.
*
* @return true if all the options are valid.
*/
public boolean generalValidOptions() {
boolean docencodingfound = false;
for (Doclet.Option opt : optionsProcessed) {
if (opt.matches("-docencoding")) {
docencodingfound = true;
if (!checkOutputFileEncoding(docencoding)) {
return false;
}
if (docencoding != null) {
if (!checkOutputFileEncoding(docencoding)) {
return false;
}
}
if (!docencodingfound && (encoding != null && !encoding.isEmpty())) {
if (docencoding == null && (encoding != null && !encoding.isEmpty())) {
if (!checkOutputFileEncoding(encoding)) {
return false;
}
@ -897,35 +916,6 @@ public abstract class Configuration {
: utils.getFullyQualifiedName(te);
}
// cache these, as they are repeatedly called.
private Set<TypeElement> specifiedClasses = null;
private Set<PackageElement> specifiedPackages = null;
private Set<ModuleElement> specifiedModules = null;
public Set<TypeElement> getSpecifiedClasses() {
if (specifiedClasses == null) {
specifiedClasses = new LinkedHashSet<>(
ElementFilter.typesIn(docEnv.getSpecifiedElements()));
}
return specifiedClasses;
}
public Set<PackageElement> getSpecifiedPackages() {
if (specifiedPackages == null) {
specifiedPackages = new LinkedHashSet<>(
ElementFilter.packagesIn(docEnv.getSpecifiedElements()));
}
return specifiedPackages;
}
public Set<ModuleElement> getSpecifiedModules() {
if (specifiedModules == null) {
specifiedModules = new LinkedHashSet<>(
ElementFilter.modulesIn(docEnv.getSpecifiedElements()));
}
return specifiedModules;
}
/**
* Convenience method to obtain a resource from the doclet's
* {@link Resources resources}.
@ -1058,7 +1048,7 @@ public abstract class Configuration {
public abstract boolean showMessage(Element e, String key);
public static abstract class Option implements Doclet.Option, Comparable<Option> {
private final String name;
private final String[] names;
private final String parameters;
private final String description;
private final int argCount;
@ -1068,7 +1058,7 @@ public abstract class Configuration {
}
protected Option(Resources resources, String keyBase, String name, int argCount) {
this.name = name;
this.names = name.trim().split("\\s+");
String desc = getOptionsMessage(resources, keyBase + ".description");
if (desc.isEmpty()) {
this.description = "<MISSING KEY>";
@ -1103,8 +1093,8 @@ public abstract class Configuration {
}
@Override
public String getName() {
return name;
public List<String> getNames() {
return Arrays.asList(names);
}
@Override
@ -1114,7 +1104,7 @@ public abstract class Configuration {
@Override
public String toString() {
return name;
return names.toString();
}
@Override
@ -1122,21 +1112,22 @@ public abstract class Configuration {
return argCount;
}
@Override
public boolean matches(String option) {
boolean matchCase = name.startsWith("--");
if (option.startsWith("--") && option.contains("=")) {
return name.equals(option.substring(option.indexOf("=") + 1));
} else if (matchCase) {
return name.equals(option);
} else {
for (String name : names) {
boolean matchCase = name.startsWith("--");
if (option.startsWith("--") && option.contains("=")) {
return name.equals(option.substring(option.indexOf("=") + 1));
} else if (matchCase) {
return name.equals(option);
}
return name.toLowerCase().equals(option.toLowerCase());
}
return false;
}
@Override
public int compareTo(Option that) {
return this.getName().compareTo(that.getName());
return this.getNames().get(0).compareTo(that.getNames().get(0));
}
}
@ -1187,4 +1178,54 @@ public abstract class Configuration {
this.value2 = value2;
}
}
/*
* Splits the elements in a collection to its individual
* collection.
*/
static private class Splitter {
final Set<ModuleElement> mset = new LinkedHashSet<>();
final Set<PackageElement> pset = new LinkedHashSet<>();
final Set<TypeElement> tset = new LinkedHashSet<>();
Splitter(DocletEnvironment docEnv, boolean included) {
Set<? extends Element> inset = included
? docEnv.getIncludedElements()
: docEnv.getSpecifiedElements();
for (Element e : inset) {
new SimpleElementVisitor9<Void, Void>() {
@Override
@DefinedBy(Api.LANGUAGE_MODEL)
public Void visitModule(ModuleElement e, Void p) {
mset.add(e);
return null;
}
@Override
@DefinedBy(Api.LANGUAGE_MODEL)
public Void visitPackage(PackageElement e, Void p) {
pset.add(e);
return null;
}
@Override
@DefinedBy(Api.LANGUAGE_MODEL)
public Void visitType(TypeElement e, Void p) {
tset.add(e);
return null;
}
@Override
@DefinedBy(Api.LANGUAGE_MODEL)
protected Void defaultAction(Element e, Void p) {
throw new AssertionError("unexpected element: " + e);
}
}.visit(e);
}
}
}
}

10
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java
View File

@ -187,11 +187,6 @@ public class WorkArounds {
return ((Attribute)aDesc).isSynthesized();
}
// TODO: implement using jx.l.model
public boolean isVisible(TypeElement te) {
return ((DocEnvImpl)(configuration.docEnv)).etable.isVisible(te);
}
// TODO: fix the caller
public Object getConstValue(VariableElement ve) {
return ((VarSymbol)ve).getConstValue();
@ -286,11 +281,6 @@ public class WorkArounds {
return null;
}
// TODO: investigate and reimplement without javac dependencies.
public boolean shouldDocument(Element e) {
return ((DocEnvImpl)(configuration.docEnv)).etable.shouldDocument(e);
}
// TODO: jx.l.m ?
public Location getLocationForModule(ModuleElement mdle) {
ModuleSymbol msym = (ModuleSymbol)mdle;

2
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java
View File

@ -129,7 +129,7 @@ public class SerializedFormBuilder extends AbstractBuilder {
@Override
public void build() throws DocletException {
SortedSet<TypeElement> rootclasses = new TreeSet<>(utils.makeGeneralPurposeComparator());
rootclasses.addAll(configuration.docEnv.getIncludedTypeElements());
rootclasses.addAll(configuration.getIncludedTypeElements());
if (!serialClassFoundToDocument(rootclasses)) {
//Nothing to document.
return;

4
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java
View File

@ -117,7 +117,7 @@ public class ClassTree {
baseEnums = new TreeSet<>(comparator);
baseClasses = new TreeSet<>(comparator);
baseInterfaces = new TreeSet<>(comparator);
buildTree(configuration.docEnv.getIncludedTypeElements());
buildTree(configuration.getIncludedTypeElements());
}
/**
@ -134,7 +134,7 @@ public class ClassTree {
baseEnums = new TreeSet<>(comparator);
baseClasses = new TreeSet<>(comparator);
baseInterfaces = new TreeSet<>(comparator);
buildTree(configuration.docEnv.getIncludedTypeElements());
buildTree(configuration.getIncludedTypeElements());
}
/**

2
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java
View File

@ -206,7 +206,7 @@ public class ClassUseMapper {
implementingClasses(intfc);
}
// Map methods, fields, constructors using a class.
Set<TypeElement> classes = docEnv.getIncludedTypeElements();
Set<TypeElement> classes = configuration.getIncludedTypeElements();
for (TypeElement aClass : classes) {
PackageElement pkg = elementUtils.getPackageOf(aClass);
mapAnnotations(classToPackageAnnotations, pkg, pkg);

2
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java
View File

@ -96,7 +96,7 @@ public class DeprecatedAPIListBuilder {
}
}
deprecatedMap.put(DeprElementKind.PACKAGE, pset);
for (Element e : configuration.docEnv.getIncludedTypeElements()) {
for (Element e : configuration.getIncludedTypeElements()) {
TypeElement te = (TypeElement)e;
SortedSet<Element> eset;
if (utils.isDeprecated(e)) {

4
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java
View File

@ -126,8 +126,8 @@ public class IndexBuilder {
* @param docEnv the doclet environment
*/
protected void buildIndexMap(DocletEnvironment docEnv) {
Set<PackageElement> packages = configuration.getSpecifiedPackages();
Set<TypeElement> classes = docEnv.getIncludedTypeElements();
Set<PackageElement> packages = configuration.getSpecifiedPackageElements();
Set<TypeElement> classes = configuration.getIncludedTypeElements();
if (!classesOnly) {
if (packages.isEmpty()) {
Set<PackageElement> set = new HashSet<>();

46
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
View File

@ -2263,22 +2263,22 @@ public class Utils {
private List<TypeElement> getInnerClasses(Element e, boolean filter) {
List<TypeElement> olist = new ArrayList<>();
for (TypeElement te : getClassesUnfiltered(e)) {
if (!filter || configuration.workArounds.isVisible(te)) {
if (!filter || configuration.docEnv.isSelected(te)) {
olist.add(te);
}
}
for (TypeElement te : getInterfacesUnfiltered(e)) {
if (!filter || configuration.workArounds.isVisible(te)) {
if (!filter || configuration.docEnv.isSelected(te)) {
olist.add(te);
}
}
for (TypeElement te : getAnnotationTypesUnfiltered(e)) {
if (!filter || configuration.workArounds.isVisible(te)) {
if (!filter || configuration.docEnv.isSelected(te)) {
olist.add(te);
}
}
for (TypeElement te : getEnumsUnfiltered(e)) {
if (!filter || configuration.workArounds.isVisible(te)) {
if (!filter || configuration.docEnv.isSelected(te)) {
olist.add(te);
}
}
@ -2361,7 +2361,7 @@ public class Utils {
List<Element> elements = new ArrayList<>();
for (Element e : te.getEnclosedElements()) {
if (kinds.contains(e.getKind())) {
if (!filter || configuration.workArounds.shouldDocument(e)) {
if (!filter || shouldDocument(e)) {
elements.add(e);
}
}
@ -2369,6 +2369,36 @@ public class Utils {
return elements;
}
private SimpleElementVisitor9<Boolean, Void> shouldDocumentVisitor = null;
private boolean shouldDocument(Element e) {
if (shouldDocumentVisitor == null) {
shouldDocumentVisitor = new SimpleElementVisitor9<Boolean, Void>() {
private boolean hasSource(TypeElement e) {
return configuration.docEnv.getFileKind(e) ==
javax.tools.JavaFileObject.Kind.SOURCE;
}
// handle types
@Override
public Boolean visitType(TypeElement e, Void p) {
return configuration.docEnv.isSelected(e) && hasSource(e);
}
// handle everything else
@Override
protected Boolean defaultAction(Element e, Void p) {
return configuration.docEnv.isSelected(e);
}
@Override
public Boolean visitUnknown(Element e, Void p) {
throw new AssertionError("unkown element: " + p);
}
};
}
return shouldDocumentVisitor.visit(e);
}
/*
* nameCache is maintained for improving the comparator
* performance, noting that the Collator used by the comparators
@ -2578,17 +2608,17 @@ public class Utils {
specifiedVisitor = new SimpleElementVisitor9<Boolean, Void>() {
@Override
public Boolean visitModule(ModuleElement e, Void p) {
return configuration.getSpecifiedModules().contains(e);
return configuration.getSpecifiedModuleElements().contains(e);
}
@Override
public Boolean visitPackage(PackageElement e, Void p) {
return configuration.getSpecifiedPackages().contains(e);
return configuration.getSpecifiedPackageElements().contains(e);
}
@Override
public Boolean visitType(TypeElement e, Void p) {
return configuration.getSpecifiedClasses().contains(e);
return configuration.getSpecifiedTypeElements().contains(e);
}
@Override

52
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/DocEnvImpl.java
View File

@ -25,19 +25,15 @@
package jdk.javadoc.internal.tool;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import java.util.stream.Collectors;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.Elements;
import javax.lang.model.util.Types;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileObject.Kind;
import com.sun.source.util.DocTrees;
import com.sun.tools.javac.code.Source;
@ -74,24 +70,14 @@ public class DocEnvImpl implements DocletEnvironment {
this.toolEnv = toolEnv;
this.etable = etable;
}
@Override
public Set<ModuleElement> getIncludedModuleElements() {
return etable.getIncludedModuleElements();
@Override
public Set<? extends Element> getSpecifiedElements() {
return etable.getSpecifiedElements();
}
@Override
public Set<PackageElement> getIncludedPackageElements() {
return etable.getIncludedPackageElements();
}
/**
* Return all TypeElements (including those inside
* packages) to be documented.
*/
@Override
public Set<TypeElement> getIncludedTypeElements() {
return etable.getIncludedTypeElements();
public Set<? extends Element> getIncludedElements() {
return etable.getIncludedElements();
}
@Override
@ -109,22 +95,6 @@ public class DocEnvImpl implements DocletEnvironment {
return toolEnv.elements;
}
@Override
public List<Element> getSelectedElements(List<? extends Element> elements) {
return elements.stream()
.filter(e -> isIncluded(e))
.collect(Collectors.<Element>toList());
}
@Override
public Set<Element> getSpecifiedElements() {
Set<Element> out = new LinkedHashSet<>();
out.addAll(etable.getSpecifiedModuleElements());
out.addAll(etable.getSpecifiedPackageElements());
out.addAll(etable.getSpecifiedTypeElements());
return out;
}
@Override
public Types getTypeUtils() {
return toolEnv.typeutils;
@ -144,4 +114,14 @@ public class DocEnvImpl implements DocletEnvironment {
public ModuleMode getModuleMode() {
return etable.getModuleMode();
}
@Override
public Kind getFileKind(TypeElement type) {
return toolEnv.getFileKind(type);
}
@Override
public boolean isSelected(Element e) {
return etable.isSelected(e);
}
}

223
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java
View File

@ -137,7 +137,7 @@ import static jdk.javadoc.internal.tool.JavadocTool.isValidClassName;
* Rules for processing:
*
* 1. A specified element, meaning an element given on the
* command-line, and exposed via getSpecifiedElements()
* command-line, and exposed via specified elements collections.
* 2. Expand-contents, an internal pseudo term, meaning
* it is part of the recursive expansion of specified
* elements, meaning, the modules are expanded first, then
@ -230,8 +230,28 @@ public class ElementsTable {
}
}
private Set<Element> specifiedElements = null;
/**
* Returns the selected/included module elements.
* Returns a set of elements specified on the
* command line, including any inner classes.
*
* @return the set of elements specified on the command line
*/
public Set<? extends Element> getSpecifiedElements() {
if (specifiedElements == null) {
Set<Element> result = new LinkedHashSet<>();
result.addAll(specifiedModuleElements);
result.addAll(specifiedPackageElements);
result.addAll(specifiedTypeElements);
specifiedElements = Collections.unmodifiableSet(result);
}
return specifiedElements;
}
private Set<Element> includedElements = null;
/**
* Returns a set of elements included elements. The inclusion is as
* follows:
* A module is fully included,
* - is specified on the command line --module
* - is derived from the module graph, that is, by expanding the
@ -239,14 +259,7 @@ public class ElementsTable {
*
* A module is included if an enclosed package or type is
* specified on the command line.
* @return the included module elements
*/
public Set<ModuleElement> getIncludedModuleElements() {
return includedModuleElements;
}
/**
* Returns the selected/included package elements.
*
* A package is fully included,
* - is specified on the command line
* - is derived from expanding -subpackages
@ -255,66 +268,32 @@ public class ElementsTable {
* A package is included, if an enclosed package or a type is specified on
* the command line.
*
* @return the included package elements
*/
public Set<PackageElement> getIncludedPackageElements() {
return includedPackageElements;
}
/**
* Returns the selected/included type elements (including those
* within specified or included packages) to be documented.
* Included type elements (including those within specified or included packages)
* to be documented.
*
* A type is fully included if
* - is specified on the command line with -sourcepath
* - is visible with --show-types filter
* A nested type is fully included if
* - is visible with --show-types filter
* - is enclosed in a fully included type
*
* @return the included type elements
* to be documented
* @return the set of elements specified on the command line
*/
public Set<TypeElement> getIncludedTypeElements() {
return includedTypeElements;
}
/**
* Returns a set of module elements specified on the
* command line.
* @return the set of module elements specified on the
* command line
*/
public Set<ModuleElement> getSpecifiedModuleElements() {
return specifiedModuleElements;
}
/**
* Returns a set of package elements specified on the
* command line. These may also contain children packages
* if specified with -subpackage.
*
* @return the set of package elements specified on the
* command line
*/
public Set<PackageElement> getSpecifiedPackageElements() {
return specifiedPackageElements;
}
/**
* Returns a set of type elements specified on the
* command line, including any inner classes.
*
* @return the set of type elements specified on the command line
*/
public Set<TypeElement> getSpecifiedTypeElements() {
return specifiedTypeElements;
public Set<? extends Element> getIncludedElements() {
if (includedElements == null) {
Set<Element> result = new LinkedHashSet<>();
result.addAll(includedModuleElements);
result.addAll(includedPackageElements);
result.addAll(includedTypeElements);
includedElements = Collections.unmodifiableSet(result);
}
return includedElements;
}
private IncludedVisitor includedVisitor = null;
/**
* Returns true if the given element is included or selected for
* consideration.
* Returns true if the given element is included for consideration.
* This method accumulates elements in the cache as enclosed elements of
* fully included elements are tested.
* A member (constructor, method, field) is included if
@ -539,7 +518,7 @@ public class ElementsTable {
ListBuffer<ModuleElement> queue = new ListBuffer<>();
// expand each specified module
for (ModuleElement mdle : getSpecifiedModuleElements()) {
for (ModuleElement mdle : specifiedModuleElements) {
result.add(mdle); // a specified module is included
queue.append(mdle);
Set<ModuleElement> publicRequires = getModuleRequires(mdle, true);
@ -700,7 +679,7 @@ public class ElementsTable {
*/
private void computeSpecifiedTypes() throws ToolException {
Set<TypeElement> classes = new LinkedHashSet<>();
classDecList.stream().filter((def) -> (shouldDocument(def.sym))).forEach((def) -> {
classDecList.forEach((def) -> {
TypeElement te = (TypeElement) def.sym;
if (te != null) {
addAllClasses(classes, te, true);
@ -853,17 +832,14 @@ public class ElementsTable {
try {
// eliminate needless checking, do this first.
if (list.contains(klass)) return;
if (toolEnv.isSynthetic(klass)) return;
// ignore classes with invalid Java class names
if (!JavadocTool.isValidClassName(klass.name.toString())) return;
if (filtered && !shouldDocument(klass)) return;
if (filtered && !isTypeElementSelected(klass)) return;
list.add(klass);
for (Symbol sym : klass.members().getSymbols(NON_RECURSIVE)) {
if (sym != null && sym.kind == Kind.TYP) {
ClassSymbol s = (ClassSymbol)sym;
if (!toolEnv.isSynthetic(s)) {
addAllClasses(list, s, filtered);
}
addAllClasses(list, s, filtered);
}
}
} catch (CompletionFailure e) {
@ -882,92 +858,65 @@ public class ElementsTable {
boolean filtered = true;
PackageSymbol sym = (PackageSymbol)pkg;
for (Symbol isym : sym.members().getSymbols(NON_RECURSIVE)) {
if (isym != null) {
ClassSymbol s = (ClassSymbol)isym;
if (!toolEnv.isSynthetic(sym)) {
addAllClasses(list, s, filtered);
}
}
addAllClasses(list, (TypeElement)isym, filtered);
}
}
SimpleElementVisitor9<Boolean, Void> shouldDocumentVisitor = null;
/**
* Returns whether an element ought to be documented.
* @param e the element in question
* @return true if the element should be documented
*/
public boolean shouldDocument(Element e) {
if (shouldDocumentVisitor == null) {
shouldDocumentVisitor = new SimpleElementVisitor9<Boolean, Void>() {
private boolean isTypeElementSelected(TypeElement te) {
return (xclasses || toolEnv.isFromSource(te)) && isSelected(te);
}
SimpleElementVisitor9<Boolean, Void> visibleElementVisitor = null;
/**
* Returns true if the element is selected, by applying
* the access filter checks. Special treatment is applied to
* types, for a top level type the access filter applies completely,
* however if is a nested type then it is allowed either if
* the enclosing is a static or the enclosing is also selected.
*
* @param e the element to be checked
* @return true if the element is visible
*/
public boolean isSelected(Element e) {
if (toolEnv.isSynthetic((Symbol) e)) {
return false;
}
if (visibleElementVisitor == null) {
visibleElementVisitor = new SimpleElementVisitor9<Boolean, Void>() {
@Override
public Boolean visitType(TypeElement e, Void p) {
return shouldDocument((ClassSymbol) e);
if (!accessFilter.checkModifier(e)) {
return false; // it is not allowed
}
Element encl = e.getEnclosingElement();
// check if nested
if (encl.getKind() == ElementKind.PACKAGE)
return true; // top-level class, allow it
// is enclosed static
if (encl.getModifiers().contains(Modifier.STATIC))
return true; // allowed
// check the enclosing
return visit(encl);
}
@Override
public Boolean visitVariable(VariableElement e, Void p) {
return shouldDocument((VarSymbol) e);
}
@Override
public Boolean visitExecutable(ExecutableElement e, Void p) {
return shouldDocument((MethodSymbol) e);
}
@Override
public Boolean visitPackage(PackageElement e, Void p) {
protected Boolean defaultAction(Element e, Void p) {
return accessFilter.checkModifier(e);
}
@Override
public Boolean visitUnknown(Element e, Void p) {
throw new AssertionError("unkown element: " + p);
}
};
}
return shouldDocumentVisitor.visit(e);
}
/** Check whether this member should be documented. */
private boolean shouldDocument(VarSymbol sym) {
if (toolEnv.isSynthetic(sym)) {
return false;
}
return accessFilter.checkModifier(sym);
}
/** Check whether this member should be documented. */
private boolean shouldDocument(MethodSymbol sym) {
if (toolEnv.isSynthetic(sym)) {
return false;
}
return accessFilter.checkModifier(sym);
}
/** Check whether this class should be documented. */
private boolean shouldDocument(ClassSymbol sym) {
return
!toolEnv.isSynthetic(sym) && // no synthetics
(xclasses || toolEnv.hasPath(sym)) &&
isVisible(sym);
}
/**
* Returns the visibility of a type element.
* If the type element is a nested type, then check if the
* enclosing is static or the enclosed is visible.
*
* @param te the type element to be checked
* @return true if the element is visible
*/
public boolean isVisible(TypeElement te) {
ClassSymbol sym = (ClassSymbol)te;
if (!accessFilter.checkModifier(sym)) {
return false;
}
ClassSymbol encl = sym.owner.enclClass();
return (encl == null || (sym.flags_field & Flags.STATIC) != 0 || isVisible(encl));
return visibleElementVisitor.visit(e);
}
private class IncludedVisitor extends SimpleElementVisitor9<Boolean, Void> {
final private Set<Element> includedCache;
public IncludedVisitor() {
@ -991,7 +940,7 @@ public class ElementsTable {
if (includedTypeElements.contains(e)) {
return true;
}
if (shouldDocument(e)) {
if (isTypeElementSelected(e)) {
// Class is nameable from top-level and
// the class and all enclosing classes
// pass the modifier filter.
@ -1019,7 +968,7 @@ public class ElementsTable {
public Boolean defaultAction(Element e, Void p) {
if (includedCache.contains(e))
return true;
if (visit(e.getEnclosingElement()) && shouldDocument(e)) {
if (visit(e.getEnclosingElement()) && isSelected(e)) {
switch(e.getKind()) {
case ANNOTATION_TYPE: case CLASS: case ENUM: case INTERFACE:
case MODULE: case OTHER: case PACKAGE:

1
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocEnter.java
View File

@ -99,6 +99,7 @@ public class JavadocEnter extends Enter {
if (tree.sym.kind == TYP || tree.sym.kind == ERR) {
ClassSymbol c = tree.sym;
toolEnv.setElementToTreePath(c, toolEnv.getTreePath(env.toplevel, tree));
c.classfile = env.toplevel.sourcefile;
}
}

34
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java
View File

@ -62,6 +62,7 @@ import com.sun.tools.javac.util.Context;
import com.sun.tools.javac.util.Log;
import com.sun.tools.javac.util.Log.WriterKind;
import com.sun.tools.javac.util.Options;
import com.sun.tools.javac.util.StringUtils;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.Doclet.Option;
@ -233,7 +234,7 @@ public class Start extends ToolOption.Helper {
@Override
public int compare(Doclet.Option o1, Doclet.Option o2) {
return collator.compare(o1.getName(), o2.getName());
return collator.compare(o1.getNames().get(0), o2.getNames().get(0));
}
};
@ -244,10 +245,11 @@ public class Start extends ToolOption.Helper {
}
void showDocletOption(Doclet.Option option) {
List<String> names = Arrays.asList(option.getName());
List<String> names = option.getNames();
String parameters;
if (option.getArgumentCount() > 0 || option.getName().endsWith(":")) {
String sep = option.getName().endsWith(":") ? "" : " ";
String optname = names.get(0);
if (option.getArgumentCount() > 0 || optname.endsWith(":")) {
String sep = optname.endsWith(":") ? "" : " ";
parameters = sep + option.getParameters();
} else {
parameters = "";
@ -610,7 +612,23 @@ public class Start extends ToolOption.Helper {
return ok;
}
Set<Doclet.Option> docletOptions = null;
boolean matches(List<String> names, String arg) {
for (String name : names) {
if (StringUtils.toLowerCase(name).equals(StringUtils.toLowerCase(arg)))
return true;
}
return false;
}
boolean matches(Doclet.Option option, String arg) {
if (matches(option.getNames(), arg))
return true;
int sep = arg.indexOf(':');
String targ = arg.substring(0, sep + 1);
return matches(option.getNames(), targ);
}
Set<? extends Doclet.Option> docletOptions = null;
int handleDocletOptions(int idx, List<String> args, boolean isToolOption)
throws OptionException {
if (docletOptions == null) {
@ -628,14 +646,14 @@ public class Start extends ToolOption.Helper {
}
String text = null;
for (Doclet.Option opt : docletOptions) {
if (opt.matches(argBase)) {
if (matches(opt, argBase)) {
if (argVal != null) {
switch (opt.getArgumentCount()) {
case 0:
text = messager.getText("main.unnecessary_arg_provided", argBase);
throw new OptionException(ERROR, this::usage, text);
case 1:
opt.process(arg, Arrays.asList(argVal).listIterator());
opt.process(arg, Arrays.asList(argVal));
break;
default:
text = messager.getText("main.only_one_argument_with_equals", argBase);
@ -646,7 +664,7 @@ public class Start extends ToolOption.Helper {
text = messager.getText("main.requires_argument", arg);
throw new OptionException(ERROR, this::usage, text);
}
opt.process(arg, args.listIterator(idx + 1));
opt.process(arg, args.subList(idx + 1, args.size()));
idx += opt.getArgumentCount();
}
return idx;

18
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java
View File

@ -34,6 +34,7 @@ import javax.lang.model.element.TypeElement;
import javax.lang.model.util.Elements;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileObject;
import javax.tools.JavaFileObject.Kind;
import com.sun.source.util.DocTrees;
import com.sun.source.util.TreePath;
@ -193,17 +194,20 @@ public class ToolEnvironment {
}
/**
* Returns true if the symbol has a tree path associated with it.
* Primarily used to disambiguate a symbol associated with a source
* Returns true if the type element originates from source.
* Primarily used to disambiguate a type element associated with a source
* file versus a class file.
* @param sym the symbol to be checked
* @return true if the symbol has a tree path
* @param te the type element
* @return true if the symbol is from source
*/
boolean hasPath(ClassSymbol sym) {
TreePath path = elementToTreePath.get(sym);
return path != null;
public boolean isFromSource(TypeElement te) {
return getFileKind(te) == Kind.SOURCE;
}
public Kind getFileKind(TypeElement te) {
JavaFileObject jfo = ((ClassSymbol)te).outermostClass().classfile;
return jfo == null ? Kind.SOURCE : jfo.getKind();
}
/**
* Print a notice, iff <em>quiet</em> is not specified.
*

21
langtools/test/jdk/javadoc/doclet/testBaseClass/BaseClass.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2016, 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
@ -39,14 +39,18 @@
*/
import java.util.Collections;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.stream.Collectors;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import javax.lang.model.util.Elements;
import jdk.javadoc.doclet.*;
@ -60,17 +64,17 @@ public class BaseClass implements Doclet {
throw new AssertionError("Base class is not included: baz.Foo");
}
for (Element e : root.getSpecifiedElements()) {
if (e.getKind() == ElementKind.CLASS &&
e.getSimpleName().contentEquals("Bar")) {
klass = (TypeElement)e;
for (TypeElement te : ElementFilter.typesIn(root.getSpecifiedElements())) {
if (te.getKind() == ElementKind.CLASS &&
te.getSimpleName().contentEquals("Bar")) {
klass = te;
}
}
if (klass == null) {
throw new AssertionError("class Bar not found");
}
List<? extends Element> members = klass.getEnclosedElements();
List<Element> selected = root.getSelectedElements(members);
boolean foundPublic = false;
boolean foundProtected = false;
@ -78,8 +82,11 @@ public class BaseClass implements Doclet {
boolean foundPackagePrivate = false;
boolean foundPrivate = false;
List<Element> included = members.stream()
.filter(cls -> root.isIncluded(cls))
.collect(Collectors.toList());
for (Element e :selected) {
for (Element e : included) {
System.out.println("element: " + e);
if (e.getSimpleName().toString().equals("aPublicMethod")) {
foundPublic = true;

31
langtools/test/jdk/javadoc/tool/6227454/Test.java
View File

@ -25,19 +25,21 @@
* @test
* @bug 6227454
* @summary package.html and overview.html may not be read fully
* * @modules jdk.javadoc/jdk.javadoc.internal.tool
* @modules jdk.javadoc/jdk.javadoc.internal.tool
*/
import java.io.*;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.ListIterator;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.util.ElementFilter;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.util.DocTrees;
@ -45,7 +47,6 @@ import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.Reporter;
import jdk.javadoc.doclet.DocletEnvironment;
public class Test implements Doclet {
public static void main(String... args) throws Exception {
new Test().run();
@ -140,9 +141,9 @@ public class Test implements Doclet {
public boolean run(DocletEnvironment root) {
DocTrees docTrees = root.getDocTrees();
System.out.println("classes:" + root.getIncludedTypeElements());
System.out.println("classes:" + ElementFilter.typesIn(root.getIncludedElements()));
Element klass = root.getIncludedTypeElements().iterator().next();
Element klass = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
String text = "";
try {
DocCommentTree dcTree = docTrees.getDocCommentTree(klass, overviewpath);
@ -190,8 +191,10 @@ public class Test implements Doclet {
}
@Override
public String getName() {
return "overview";
public List<String> getNames() {
List<String> out = new ArrayList<>();
out.add("overview");
return out;
}
@Override
@ -200,21 +203,13 @@ public class Test implements Doclet {
}
@Override
public boolean matches(String option) {
String opt = option.startsWith("-") ? option.substring(1) : option;
return getName().equals(opt);
}
@Override
public boolean process(String option, ListIterator<String> arguments) {
if (matches(option)) {
overviewpath = arguments.next();
}
public boolean process(String option, List<String> arguments) {
overviewpath = arguments.get(0);
return true;
}
}
};
return new HashSet<Option>(Arrays.asList(options));
return new HashSet<>(Arrays.asList(options));
}
@Override

3
langtools/test/jdk/javadoc/tool/BreakIteratorWarning.java
View File

@ -40,6 +40,7 @@ import javax.lang.model.SourceVersion;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.util.ElementFilter;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.doctree.DocTree;
@ -75,7 +76,7 @@ public class BreakIteratorWarning implements Doclet {
}
public boolean run(DocletEnvironment root) {
TypeElement cd = root.getIncludedTypeElements().iterator().next();
TypeElement cd = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
VariableElement fd = getFields(cd).get(0);
DocTrees docTrees = root.getDocTrees();
DocCommentTree docCommentTree = docTrees.getDocCommentTree(fd);

2
langtools/test/jdk/javadoc/tool/InlineTagsWithBraces.java
View File

@ -80,7 +80,7 @@ public class InlineTagsWithBraces implements Doclet {
public boolean run(DocletEnvironment root) {
DocTrees trees = root.getDocTrees();
TypeElement cd = root.getIncludedTypeElements().iterator().next();
TypeElement cd = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
DocCommentTree docCommentTree = trees.getDocCommentTree(cd);
List<? extends DocTree> tags = docCommentTree.getBody();

3
langtools/test/jdk/javadoc/tool/NoStar.java
View File

@ -34,6 +34,7 @@ import java.util.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.util.DocTrees;
@ -62,7 +63,7 @@ public class NoStar implements Doclet
}
public boolean run(DocletEnvironment root) {
Set<TypeElement> classes = root.getIncludedTypeElements();
Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
if (classes.size() != 1)
throw new Error("1 " + Arrays.asList(classes));
TypeElement self = classes.iterator().next();

25
langtools/test/jdk/javadoc/tool/OptionSyntaxTest.java
View File

@ -40,9 +40,7 @@ import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.List;
import java.util.ListIterator;
import java.util.Locale;
import java.util.Objects;
import java.util.Set;
import javax.lang.model.SourceVersion;
@ -97,11 +95,11 @@ public class OptionSyntaxTest extends TestRunner {
}
static class DOption implements Doclet.Option {
private final String name;
private final List<String> names = new ArrayList<>();
private final int argCount;
DOption(String name, int argCount) {
this.name = name;
this.names.add(name);
this.argCount = argCount;
}
@ -112,7 +110,7 @@ public class OptionSyntaxTest extends TestRunner {
@Override
public String getDescription() {
return "description[" + name + "]";
return "description[" + names.get(0) + "]";
}
@Override
@ -121,25 +119,20 @@ public class OptionSyntaxTest extends TestRunner {
}
@Override
public String getName() {
return name;
public List<String> getNames() {
return names;
}
@Override
public String getParameters() {
return argCount > 0 ? "parameters[" + name + "," + argCount + "]" : null;
return argCount > 0 ? "parameters[" + names.get(0) + "," + argCount + "]" : null;
}
@Override
public boolean matches(String option) {
return option.equals(name);
}
@Override
public boolean process(String option, ListIterator<String> arguments) {
public boolean process(String option, List<String> arguments) {
List<String> args = new ArrayList<>();
for (int i = 0; i < argCount && arguments.hasNext(); i++) {
args.add(arguments.next());
for (int i = 0; i < argCount && i < arguments.size(); i++) {
args.add(arguments.get(i));
}
System.out.println("process " + option + " " + args);
return args.stream().filter(s -> s.startsWith("arg")).count() == argCount;

3
langtools/test/jdk/javadoc/tool/T4994049/T4994049.java
View File

@ -41,6 +41,7 @@ import javax.lang.model.SourceVersion;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import com.sun.source.tree.CompilationUnitTree;
import com.sun.source.tree.LineMap;
@ -59,7 +60,7 @@ public class T4994049 implements Doclet {
DocTrees trees = root.getDocTrees();
SourcePositions sourcePositions = trees.getSourcePositions();
for (TypeElement klass : root.getIncludedTypeElements()) {
for (TypeElement klass : ElementFilter.typesIn(root.getIncludedElements())) {
for (ExecutableElement method : getMethods(klass)) {
if (method.getSimpleName().toString().equals("tabbedMethod")) {
TreePath path = trees.getPath(method);

3
langtools/test/jdk/javadoc/tool/completionFailure/CompletionFailure.java
View File

@ -35,6 +35,7 @@ import java.util.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
@ -54,7 +55,7 @@ public class CompletionFailure implements Doclet {
}
public boolean run(DocletEnvironment root) {
Set<TypeElement> classes = root.getIncludedTypeElements();
Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
if (classes.size() != 1)
throw new Error("1 " + Arrays.asList(classes));
return true;

3
langtools/test/jdk/javadoc/tool/dupOk/DupOk.java
View File

@ -36,6 +36,7 @@ import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.Reporter;
@ -62,7 +63,7 @@ public class DupOk implements Doclet
}
public boolean run(DocletEnvironment root) {
Set<TypeElement> classes = root.getIncludedTypeElements();
Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
if (classes.size() != 2)
throw new Error("1 " + Arrays.asList(classes));
for (TypeElement clazz : classes) {

159
langtools/test/jdk/javadoc/tool/example/Example.java Normal file
View File

@ -0,0 +1,159 @@
/*
* Copyright (c) 2016, 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.
*
* 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.
*/
/*
* NOTE: this class is an almost a replica of the example used in the
* package-info.java.
*/
import java.io.IOException;
import java.util.Arrays;
import java.util.HashSet;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import javax.tools.Diagnostic.Kind;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.util.DocTrees;
import jdk.javadoc.doclet.*;
/**
* An Example class implementing the Doclet.
*/
public class Example implements Doclet {
Reporter reporter;
@Override
public void init(Locale locale, Reporter reporter) {
reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
this.reporter = reporter;
}
/**
* Prints an element.
*
* @param trees the utility class
* @param e the element to be printed
*/
public void printElement(DocTrees trees, Element e) {
DocCommentTree docCommentTree = trees.getDocCommentTree(e);
if (docCommentTree != null) {
System.out.println("Element (" + e.getKind() + ": "
+ e + ") has the following comments:");
System.out.println("Entire body: " + docCommentTree.getFullBody());
System.out.println("Block tags: " + docCommentTree.getBlockTags());
}
}
@Override
public boolean run(DocletEnvironment docEnv) {
reporter.print(Kind.NOTE, "overviewfile: " + overviewfile);
// get the DocTrees utility class to access DocComments
DocTrees docTrees = docEnv.getDocTrees();
// location of an element in the same directory as overview.html
try {
Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
DocCommentTree docCommentTree
= docTrees.getDocCommentTree(e, overviewfile);
if (docCommentTree != null) {
System.out.println("Overview html: " + docCommentTree.getFullBody());
}
} catch (IOException missing) {
reporter.print(Kind.ERROR, "No overview.html found.");
}
for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
System.out.println(t.getKind() + ":" + t);
for (Element e : t.getEnclosedElements()) {
printElement(docTrees, e);
}
}
return true;
}
@Override
public String getName() {
return "Example";
}
private String overviewfile;
@Override
public Set<? extends Option> getSupportedOptions() {
Option[] options = {
new Option() {
private final List<String> someOption = Arrays.asList(
"-overviewfile",
"-overview-file",
"--over-view-file"
);
@Override
public int getArgumentCount() {
return 1;
}
@Override
public String getDescription() {
return "an option with aliases";
}
@Override
public Option.Kind getKind() {
return Option.Kind.STANDARD;
}
@Override
public List<String> getNames() {
return someOption;
}
@Override
public String getParameters() {
return "file";
}
@Override
public boolean process(String opt, List<String> arguments) {
overviewfile = arguments.get(0);
return true;
}
}
};
return new HashSet<>(Arrays.asList(options));
}
@Override
public SourceVersion getSupportedSourceVersion() {
// support the latest release
return SourceVersion.latest();
}
}

116
langtools/test/jdk/javadoc/tool/example/Tester.java Normal file
View File

@ -0,0 +1,116 @@
/*
* Copyright (c) 2016, 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.
*
* 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.
*/
/*
* @test
* @bug 8164316
* @summary tests the example used in package-info.java and doclet options.
* @modules
* jdk.javadoc/jdk.javadoc.internal.api
* jdk.javadoc/jdk.javadoc.internal.tool
* jdk.compiler/com.sun.tools.javac.api
* jdk.compiler/com.sun.tools.javac.main
* @library /tools/lib
* @build toolbox.ToolBox toolbox.TestRunner Example
* @run main Tester
*/
import java.io.File;
import java.util.Arrays;
import java.util.ArrayList;
import java.util.List;
import toolbox.*;
import toolbox.Task.Expect;
import static toolbox.Task.OutputKind.*;
public class Tester extends TestRunner {
final ToolBox tb;
final File testFile;
final File testSrc;
final Class<?> docletClass;
final static String OV_FN = "overview.html";
Tester() {
super(System.err);
testSrc = new File(System.getProperty("test.src"));
testFile = new File(testSrc, "Example.java");
tb = new ToolBox();
ClassLoader cl = Tester.class.getClassLoader();
try {
docletClass = cl.loadClass("Example");
} catch (ClassNotFoundException cfe) {
throw new Error(cfe);
}
}
public static void main(String... args) throws Exception {
new Tester().runTests();
}
private Task.Result execTask(String... extraArgs) {
return execTask(false, extraArgs);
}
private Task.Result execTask(boolean isNegative, String... extraArgs) {
JavadocTask et = new JavadocTask(tb, Task.Mode.API);
et.docletClass(docletClass);
List<String> args = new ArrayList<>();
args.add("-sourcepath");
args.add(testSrc.getAbsolutePath());
args.add(testFile.getAbsolutePath());
args.addAll(Arrays.asList(extraArgs));
//args.forEach((a -> System.err.println("arg: " + a)));
System.err.println(Arrays.asList(extraArgs));
Task.Result result = isNegative
? et.options(args).run(Expect.FAIL)
: et.options(args).run();
return result;
}
void assertPresence(String regex, List<String> output) throws Exception {
List<String> foundList = tb.grep(regex, output);
if (foundList.isEmpty()) {
throw new Exception("Not found, expected: " + regex);
}
}
@Test
public void testOption() throws Exception {
Task.Result result = execTask("-overviewfile", OV_FN);
assertPresence("overviewfile: " + OV_FN, result.getOutputLines(DIRECT));
}
@Test
public void testOptionAlias() throws Exception {
Task.Result result = execTask("-overview-file", OV_FN);
assertPresence("overviewfile: " + OV_FN, result.getOutputLines(DIRECT));
}
@Test
public void testOptionAliasDoubleDash() throws Exception {
Task.Result result = execTask("--over-view-file", OV_FN);
assertPresence("overviewfile: " + OV_FN, result.getOutputLines(DIRECT));
}
}

27
langtools/test/jdk/javadoc/tool/example/overview.html Normal file
View File

@ -0,0 +1,27 @@
<!--
* Copyright (c) 2016, 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.
*
* 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.
-->
<html>
<body>
A sample html document.
</body>
</html>

16
langtools/test/jdk/javadoc/tool/modules/ModuleTestBase.java
View File

@ -32,6 +32,7 @@ import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.TreeSet;
import java.util.stream.Collectors;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
@ -336,9 +337,7 @@ public class ModuleTestBase extends TestRunner {
public boolean run(DocletEnvironment docenv) {
ps.println("ModuleMode" + FS + docenv.getModuleMode());
printDataSet("Specified", docenv.getSpecifiedElements());
printDataSet("Included", docenv.getIncludedModuleElements());
printDataSet("Included", docenv.getIncludedPackageElements());
printDataSet("Included", docenv.getIncludedTypeElements());
printDataSet("Included", docenv.getIncludedElements());
printDataSet("Selected", getAllSelectedElements(docenv));
System.out.println(sw);
return true;
@ -353,21 +352,24 @@ public class ModuleTestBase extends TestRunner {
if (rc != 0) return rc;
return Integer.compare(e1.hashCode(), e2.hashCode());
});
for (ModuleElement me : docenv.getIncludedModuleElements()) {
Set<? extends Element> elements = docenv.getIncludedElements();
for (ModuleElement me : ElementFilter.modulesIn(elements)) {
addEnclosedElements(docenv, result, me);
}
for (PackageElement pe : docenv.getIncludedPackageElements()) {
for (PackageElement pe : ElementFilter.packagesIn(elements)) {
addEnclosedElements(docenv, result, docenv.getElementUtils().getModuleOf(pe));
addEnclosedElements(docenv, result, pe);
}
for (TypeElement te : docenv.getIncludedTypeElements()) {
for (TypeElement te : ElementFilter.typesIn(elements)) {
addEnclosedElements(docenv, result, te);
}
return result;
}
void addEnclosedElements(DocletEnvironment docenv, Set<Element> result, Element e) {
List<? extends Element> elems = docenv.getSelectedElements(e.getEnclosedElements());
List<Element> elems = e.getEnclosedElements().stream()
.filter(el -> docenv.isIncluded(el))
.collect(Collectors.toList());
result.addAll(elems);
for (TypeElement t : ElementFilter.typesIn(elems)) {
addEnclosedElements(docenv, result, t);

7
langtools/test/jdk/javadoc/tool/sourceOnly/p/SourceOnly.java
View File

@ -29,6 +29,8 @@ import java.util.Locale;
import java.util.Set;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.ElementFilter;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
@ -42,9 +44,10 @@ public class SourceOnly implements Doclet {
@Override
public boolean run(DocletEnvironment root) {
if (root.getIncludedTypeElements().size() != 1)
Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
if (classes.size() != 1)
throw new Error("wrong set of classes documented: " +
Arrays.asList(root.getIncludedTypeElements()));
Arrays.asList(classes));
return true;
}

3
langtools/test/jdk/javadoc/tool/sourceOption/SourceOption.java
View File

@ -61,6 +61,7 @@ import java.util.Locale;
import java.util.Set;
import javax.lang.model.SourceVersion;
import javax.lang.model.util.ElementFilter;
import javax.tools.Diagnostic.Kind;
import jdk.javadoc.doclet.Doclet;
@ -92,7 +93,7 @@ public class SourceOption implements Doclet {
}
public boolean run(DocletEnvironment root) {
root.getIncludedTypeElements();
ElementFilter.typesIn(root.getIncludedElements());
return true;
}

10
langtools/test/tools/lib/toolbox/JavadocTask.java
View File

@ -179,6 +179,16 @@ public class JavadocTask extends AbstractTask<JavadocTask> {
return this;
}
/**
* Sets the options.
* @param options the options
* @return this task object
*/
public JavadocTask options(List<String> options) {
this.options = options;
return this;
}
/**
* Sets the files to be documented.
* @param files the files