Mercurial > hg > openjdk > jdk9 > langtools
changeset 3786:76389430a13e jdk-9+147
8164316: Refine the Doclet APIs
Reviewed-by: jjg
line wrap: on
line diff
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java Thu Nov 24 20:48:52 2016 -0800 @@ -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 @@ * @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 @@ * * @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 @@ * @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 @@ * @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 @@ 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 <p1>:<p2>.." @@ -140,20 +142,13 @@ 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.
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java Thu Nov 24 20:48:52 2016 -0800 @@ -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 @@ * @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. @@ -91,25 +83,6 @@ 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 * {@link javax.lang.model.type.TypeMirror type mirrors}. @@ -119,14 +92,24 @@ 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. * * @return the file manager used to read and write files @@ -145,7 +128,15 @@ * * @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 */
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java Thu Nov 24 20:48:52 2016 -0800 @@ -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. + * <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> + * + * <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> - * 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> - * - * 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. - * <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> - * <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. + * 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> * <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; + * @Override + * public void init(Locale locale, Reporter reporter) { + * reporter.print(Kind.NOTE, "Doclet using locale: " + locale); + * this.reporter = reporter; + * } * - * public class Example implements Doclet { - * - * @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()); + * } + * } * - * @Override - * public boolean run(DocletEnvironment docEnv) { - * // cache the DocTrees utility class to access DocComments - * DocTrees docTrees = docEnv.getDocTrees(); + * @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 : 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"; + * } * - * 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; - * } + * private String overviewfile; * - * @Override - * public String getName() { - * return "Example"; - * } + * @Override + * public Set<? extends Option> getSupportedOptions() { + * Option[] options = { + * new Option() { + * private final List<String> someOption = Arrays.asList( + * "-overviewfile", + * "--overview-file", + * "-o" + * ); * - * private String someOption; + * @Override + * public int getArgumentCount() { + * return 1; + * } + * + * @Override + * public String getDescription() { + * return "an option with aliases"; + * } * - * @Override - * public Set<Option> 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<String> arguments) { - * overviewpath = arguments.next(); - * return true; - * } - * } - * }; - * return new HashSet<Option>(Arrays.asList(options)); - * } + * @Override + * public Option.Kind getKind() { + * return Option.Kind.STANDARD; + * } + * + * @Override + * public List<String> getNames() { + * return someOption; + * } + * + * @Override + * public String getParameters() { + * return "file"; + * } * - * @Override - * public SourceVersion getSupportedSourceVersion() { - * // support the latest release - * return SourceVersion.latest(); - * } + * @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(); + * } * } * </pre> * <p> - * This doclet when invoked with a command line, such as: - * <pre> - * javadoc -doclet Example -sourcepath <source-location> - * </pre> - * will produce an output, such as: + * This doclet can be invoked with a command line, 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 \ + * -overviewfile overview.html \ + * -sourcepath source-location \ + * source-location/Example.java * </pre> * * <h3><a name="migration">Migration Guide</a></h3>
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java Thu Nov 24 20:48:52 2016 -0800 @@ -54,13 +54,13 @@ * @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 @@ * @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 @@ * @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.
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java Thu Nov 24 20:48:52 2016 -0800 @@ -52,6 +52,7 @@ 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 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
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java Thu Nov 24 20:48:52 2016 -0800 @@ -288,83 +288,13 @@ 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 @@ 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 @@ 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 @@ } protected boolean checkForDeprecation(DocletEnvironment docEnv) { - for (TypeElement te : docEnv.getIncludedTypeElements()) { + for (TypeElement te : getIncludedTypeElements()) { if (isGeneratedDoc(te)) { return true; } @@ -597,227 +526,245 @@ 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; } }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java Thu Nov 24 20:48:52 2016 -0800 @@ -91,10 +91,11 @@ * 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 @@ 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
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java Thu Nov 24 20:48:52 2016 -0800 @@ -826,8 +826,8 @@ * @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, "", ""));
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java Thu Nov 24 20:48:52 2016 -0800 @@ -32,6 +32,7 @@ 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.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 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()); } }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java Thu Nov 24 20:48:52 2016 -0800 @@ -30,6 +30,7 @@ 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.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 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()); } }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java Thu Nov 24 20:48:52 2016 -0800 @@ -66,7 +66,7 @@ */ public SerializedFormWriterImpl(ConfigurationImpl configuration) { super(configuration, DocPaths.SERIALIZED_FORM); - visibleClasses = configuration.docEnv.getIncludedTypeElements(); + visibleClasses = configuration.getIncludedTypeElements(); } /**
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java Thu Nov 24 20:48:52 2016 -0800 @@ -115,13 +115,13 @@ 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.
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java Thu Nov 24 20:48:52 2016 -0800 @@ -99,8 +99,8 @@ */ @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 @@ 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 @@ * @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 @@ 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); });
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java Thu Nov 24 20:48:52 2016 -0800 @@ -33,10 +33,13 @@ 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 @@ /** * 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 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 @@ 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 @@ 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 @@ } } - 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 @@ 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 @@ 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 @@ }, 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 @@ 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 @@ } /** + * * 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 @@ : 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 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 @@ } 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 @@ } @Override - public String getName() { - return name; + public List<String> getNames() { + return Arrays.asList(names); } @Override @@ -1114,7 +1104,7 @@ @Override public String toString() { - return name; + return names.toString(); } @Override @@ -1122,21 +1112,22 @@ 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 @@ 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); + } + } + } }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java Thu Nov 24 20:48:52 2016 -0800 @@ -187,11 +187,6 @@ 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 @@ 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;
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java Thu Nov 24 20:48:52 2016 -0800 @@ -129,7 +129,7 @@ @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;
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java Thu Nov 24 20:48:52 2016 -0800 @@ -117,7 +117,7 @@ baseEnums = new TreeSet<>(comparator); baseClasses = new TreeSet<>(comparator); baseInterfaces = new TreeSet<>(comparator); - buildTree(configuration.docEnv.getIncludedTypeElements()); + buildTree(configuration.getIncludedTypeElements()); } /** @@ -134,7 +134,7 @@ baseEnums = new TreeSet<>(comparator); baseClasses = new TreeSet<>(comparator); baseInterfaces = new TreeSet<>(comparator); - buildTree(configuration.docEnv.getIncludedTypeElements()); + buildTree(configuration.getIncludedTypeElements()); } /**
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java Thu Nov 24 20:48:52 2016 -0800 @@ -206,7 +206,7 @@ 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);
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java Thu Nov 24 20:48:52 2016 -0800 @@ -96,7 +96,7 @@ } } 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)) {
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java Thu Nov 24 20:48:52 2016 -0800 @@ -126,8 +126,8 @@ * @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<>();
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java Thu Nov 24 20:48:52 2016 -0800 @@ -2263,22 +2263,22 @@ 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 @@ 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 @@ 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 @@ 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
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/DocEnvImpl.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/DocEnvImpl.java Thu Nov 24 20:48:52 2016 -0800 @@ -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 @@ 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 @@ -110,22 +96,6 @@ } @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 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); + } }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java Thu Nov 24 20:48:52 2016 -0800 @@ -137,7 +137,7 @@ * 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 @@ } } + 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 @@ * * 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 @@ * 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 - */ - 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 + * @return the set of 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 @@ 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 @@ */ 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 @@ 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 @@ 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; + private boolean isTypeElementSelected(TypeElement te) { + return (xclasses || toolEnv.isFromSource(te)) && isSelected(te); + } + + SimpleElementVisitor9<Boolean, Void> visibleElementVisitor = null; /** - * Returns whether an element ought to be documented. - * @param e the element in question - * @return true if the element should be documented + * 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 shouldDocument(Element e) { - if (shouldDocumentVisitor == null) { - shouldDocumentVisitor = new SimpleElementVisitor9<Boolean, Void>() { - + 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); + protected Boolean defaultAction(Element e, Void p) { + return accessFilter.checkModifier(e); } @Override - public Boolean visitExecutable(ExecutableElement e, Void p) { - return shouldDocument((MethodSymbol) e); - } - - @Override - public Boolean visitPackage(PackageElement e, Void p) { - return accessFilter.checkModifier(e); + 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 @@ 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 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:
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocEnter.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocEnter.java Thu Nov 24 20:48:52 2016 -0800 @@ -99,6 +99,7 @@ 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; } }
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java Thu Nov 24 20:48:52 2016 -0800 @@ -62,6 +62,7 @@ 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 @@ @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 @@ } 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 @@ 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 @@ } 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 @@ 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;
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java Thu Nov 24 11:44:37 2016 +0100 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java Thu Nov 24 20:48:52 2016 -0800 @@ -34,6 +34,7 @@ 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 @@ } /** - * 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. *
--- a/test/jdk/javadoc/doclet/testBaseClass/BaseClass.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/doclet/testBaseClass/BaseClass.java Thu Nov 24 20:48:52 2016 -0800 @@ -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 @@ 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 @@ 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;
--- a/test/jdk/javadoc/tool/6227454/Test.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/6227454/Test.java Thu Nov 24 20:48:52 2016 -0800 @@ -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.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 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 @@ } @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 @@ } @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
--- a/test/jdk/javadoc/tool/BreakIteratorWarning.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/BreakIteratorWarning.java Thu Nov 24 20:48:52 2016 -0800 @@ -40,6 +40,7 @@ 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 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);
--- a/test/jdk/javadoc/tool/InlineTagsWithBraces.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/InlineTagsWithBraces.java Thu Nov 24 20:48:52 2016 -0800 @@ -80,7 +80,7 @@ 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();
--- a/test/jdk/javadoc/tool/NoStar.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/NoStar.java Thu Nov 24 20:48:52 2016 -0800 @@ -34,6 +34,7 @@ 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 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();
--- a/test/jdk/javadoc/tool/OptionSyntaxTest.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/OptionSyntaxTest.java Thu Nov 24 20:48:52 2016 -0800 @@ -40,9 +40,7 @@ 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 @@ } 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 @@ @Override public String getDescription() { - return "description[" + name + "]"; + return "description[" + names.get(0) + "]"; } @Override @@ -121,25 +119,20 @@ } @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;
--- a/test/jdk/javadoc/tool/T4994049/T4994049.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/T4994049/T4994049.java Thu Nov 24 20:48:52 2016 -0800 @@ -41,6 +41,7 @@ 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 @@ 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);
--- a/test/jdk/javadoc/tool/completionFailure/CompletionFailure.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/completionFailure/CompletionFailure.java Thu Nov 24 20:48:52 2016 -0800 @@ -35,6 +35,7 @@ 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 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;
--- a/test/jdk/javadoc/tool/dupOk/DupOk.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/dupOk/DupOk.java Thu Nov 24 20:48:52 2016 -0800 @@ -36,6 +36,7 @@ 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 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) {
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/jdk/javadoc/tool/example/Example.java Thu Nov 24 20:48:52 2016 -0800 @@ -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(); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/jdk/javadoc/tool/example/Tester.java Thu Nov 24 20:48:52 2016 -0800 @@ -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)); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/test/jdk/javadoc/tool/example/overview.html Thu Nov 24 20:48:52 2016 -0800 @@ -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>
--- a/test/jdk/javadoc/tool/modules/ModuleTestBase.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/modules/ModuleTestBase.java Thu Nov 24 20:48:52 2016 -0800 @@ -32,6 +32,7 @@ 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 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 @@ 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);
--- a/test/jdk/javadoc/tool/sourceOnly/p/SourceOnly.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/sourceOnly/p/SourceOnly.java Thu Nov 24 20:48:52 2016 -0800 @@ -29,6 +29,8 @@ 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 @@ @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; }
--- a/test/jdk/javadoc/tool/sourceOption/SourceOption.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/jdk/javadoc/tool/sourceOption/SourceOption.java Thu Nov 24 20:48:52 2016 -0800 @@ -61,6 +61,7 @@ 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 boolean run(DocletEnvironment root) { - root.getIncludedTypeElements(); + ElementFilter.typesIn(root.getIncludedElements()); return true; }
--- a/test/tools/lib/toolbox/JavadocTask.java Thu Nov 24 11:44:37 2016 +0100 +++ b/test/tools/lib/toolbox/JavadocTask.java Thu Nov 24 20:48:52 2016 -0800 @@ -180,6 +180,16 @@ } /** + * 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 * @return this task object