diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
index 75572f35aff..103c3c8196d 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
@@ -25,7 +25,7 @@
 
 package jdk.javadoc.doclet;
 
-import java.util.ListIterator;
+import java.util.List;
 import java.util.Locale;
 import java.util.Set;
 
@@ -67,7 +67,7 @@ public interface Doclet {
      * @param locale the locale to be used
      * @param reporter the reporter to be used
      */
-    public void init(Locale locale, Reporter reporter);
+    void init(Locale locale, Reporter reporter);
 
     /**
      * Returns a name identifying the doclet. A name is a simple identifier
@@ -76,14 +76,14 @@ public interface Doclet {
      *
      * @return name of the Doclet
      */
-    public abstract String getName();
+    String getName();
 
     /**
      * Returns all the supported options.
      *
      * @return a set containing all the supported options, an empty set if none
      */
-    public Set<Option> getSupportedOptions();
+    Set<? extends Option> getSupportedOptions();
 
     /**
      * Returns the version of the Java Programming Language supported
@@ -92,7 +92,7 @@ public interface Doclet {
      * @return  the language version supported by this doclet, usually
      * the latest version
      */
-    public SourceVersion getSupportedSourceVersion();
+    SourceVersion getSupportedSourceVersion();
 
     /**
      * The entry point of the doclet. Further processing will commence as
@@ -101,7 +101,7 @@ public interface Doclet {
      * @param environment from which essential information can be extracted
      * @return true on success
      */
-    public boolean run(DocletEnvironment environment);
+    boolean run(DocletEnvironment environment);
 
     /**
      * An encapsulation of option name, aliases, parameters and descriptions
@@ -128,10 +128,12 @@ public interface Doclet {
         Option.Kind getKind();
 
         /**
-         * Returns the option name. For instance for option "-group", will return "group"
-         * @return name of the option, if set, otherwise an empty String
+         * Returns the list of names that may be used to identify the option. For instance, the
+         * list could be {@code ["-classpath", "--class-path"]} for the
+         * option "-classpath", with an alias "--class-path".
+         * @return the names of the option
          */
-        String getName();
+        List<String> getNames();
 
         /**
          * Returns the parameters of the option. For instance "name &lt;p1&gt;:&lt;p2&gt;.."
@@ -139,21 +141,14 @@ public interface Doclet {
          */
         String getParameters();
 
-        /**
-         * Checks if the given option name is handled by this option.
-         * @param option the option name with or without the leading "-"
-         * @return true if same
-         */
-        boolean matches(String option);
-
         /**
          * Processes the option and arguments as needed. This method will
          * be invoked if the given option name matches the option.
          * @param option the option
-         * @param arguments a ListIterator encapsulating the arguments
+         * @param arguments a list encapsulating the arguments
          * @return true if operation succeeded, false otherwise
          */
-        boolean process(String option, ListIterator<String> arguments);
+        boolean process(String option, List<String> arguments);
 
         /**
          * The kind of an option.
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
index c7d3ff59a83..77f298fe907 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
@@ -25,17 +25,15 @@
 
 package jdk.javadoc.doclet;
 
-import java.util.List;
 import java.util.Set;
 
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.Element;
-import javax.lang.model.element.ModuleElement;
-import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.Elements;
 import javax.lang.model.util.Types;
 import javax.tools.JavaFileManager;
+import javax.tools.JavaFileObject.Kind;
 
 import com.sun.source.util.DocTrees;
 
@@ -48,29 +46,23 @@ import com.sun.source.util.DocTrees;
  * @since 9
  */
 public interface DocletEnvironment {
-    /**
-     * Returns the <a href="package-summary.html#included">included</a>
-     * modules.
-     *
-     * @return a set of included module elements
-     */
-    Set<ModuleElement> getIncludedModuleElements();
 
     /**
-     * Returns the <a href="package-summary.html#included">included</a>
-     * annotation types, classes, interfaces and enums in all packages.
+     * Returns the elements <a href="package-summary.html#specified">specified</a>
+     * when the tool is invoked.
      *
-     * @return a set of included type elements
+     * @return the set of specified elements
      */
-    Set<TypeElement> getIncludedTypeElements();
+    Set<? extends Element> getSpecifiedElements();
 
     /**
-     * Returns the <a href="package-summary.html#included">included</a>
-     * packages.
+     * Returns the module, package and type elements that should be
+     * <a href="package-summary.html#included">included</a> in the
+     * documentation.
      *
-     * @return a set of included package elements
+     * @return the set of included elements
      */
-    Set<PackageElement> getIncludedPackageElements();
+    Set<? extends Element> getIncludedElements();
 
     /**
      * Returns an instance of the {@code DocTrees} utility class.
@@ -90,25 +82,6 @@ public interface DocletEnvironment {
      */
     Elements getElementUtils();
 
-    /**
-     * Returns the <a href="package-summary.html#included">selected</a>
-     * elements that can be documented.
-     *
-     * @param elements those that need to be checked
-     * @return elements selected, an empty list if none
-     */
-    List<Element> getSelectedElements(List<? extends Element> elements);
-
-    /**
-     * Returns the elements <a href="package-summary.html#specified">specified</a>
-     * on the command line, usually module elements, package elements and type elements.
-     * If {@code -subpackages} and {@code -exclude} options
-     * are used, return all the non-excluded packages.
-     *
-     * @return elements specified on the command line.
-     */
-    Set<Element> getSpecifiedElements();
-
     /**
      * Returns an instance of the {@code Types} utility class.
      * This class provides methods for operating on
@@ -119,13 +92,23 @@ public interface DocletEnvironment {
     Types getTypeUtils();
 
     /**
-     * Indicates if an element is <a href="package-summary.html#included">included</a>.
+     * Returns true if an element should be
+     * <a href="package-summary.html#included">included</a> in the
+     * documentation.
      *
-     * @param e the Element in question
+     * @param e the element
      * @return true if included, false otherwise
      */
     boolean isIncluded(Element e);
 
+    /**
+     * Returns true if the element is <a href="package-summary.html#selected">selected</a>.
+     *
+     * @param e the element
+     * @return true if selected, false otherwise
+     */
+    boolean isSelected(Element e);
+
     /**
      * Returns the file manager used to read and write files.
      *
@@ -145,7 +128,15 @@ public interface DocletEnvironment {
      *
      * @return the required level of module documentation
      */
-    public ModuleMode getModuleMode();
+    ModuleMode getModuleMode();
+
+    /**
+     * Returns the file kind of a type element.
+     *
+     * @param type the type element
+     * @return the file kind
+     */
+    Kind getFileKind(TypeElement type);
 
     enum ModuleMode {
         /** Indicate API level documentation is required */
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java
index 43bb4ecbebb..f29448a2ea2 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java
@@ -48,65 +48,98 @@
  * <pre>
  *    public boolean <b>run</b>(DocletEnvironment environment)
  * </pre>
- * The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the environment that the
- * doclet will be initialized with. From this environment all other information can be
- * extracted, in the form of {@link javax.lang.model} elements. One can further use the
- * APIs and utilities described by {@link javax.lang.model} to query Elements and Types.
+ * The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the
+ * environment that the doclet will be initialized with. From this environment
+ * all other information can be extracted, in the form of
+ * {@link javax.lang.model.element.Element elements}. One can further use the APIs and utilities
+ * described by {@link javax.lang.model Language Model API} to query Elements and Types.
  * <p>
  *
  * <a name="terminology"></a>
  * <h3>Terminology</h3>
  *
- * <a name="specified"></a>
- * Module, package and source file names can be provided as parameters to the
- * javadoc tool -- these are called the <em>specified</em> set containing
- * module elements, package elements and type elements.
- * <p>
- * Javadoc <em>selection control</em> can be specified with
- * {@code --show-members:value}, {@code --showtypes:value}, where value can be one of
- * the following:
- * <ul>
- * <li> public    -- considers only public elements
- * <li> protected -- considers public and protected elements
- * <li> package   -- considers public, protected and package private elements
- * <li> private   -- considers all elements
- * </ul>
+ * <dl>
+ *   <dt><a name="selected"></a>Selected</dt>
+ *     <dd>An element is considered to be <em>selected</em>, if the
+ *         <em>selection controls</em> <a href="#options">allow</a> it
+ *         to be documented. (Note that synthetic elements are never
+ *         selected.)
+ *    </dd>
  *
- * The {@code --show-package:value} where a value of "exported" or "all" can be used to
- * consider only exported packages or all packages within a module.
+ *   <dt><a name="specified"></a>Specified</dt>
+ *   <dd>The set of elements specified by the user are considered to be <em>specified
+ *       elements</em>. Specified elements provide the starting points
+ *       for determining the <em>included elements</em> to be documented.
+ *   </dd>
+ *
+ *   <dt><a name="included"></a>Included</dt>
+ *   <dd>An element is considered to be <em>included</em>, if it is
+ *       <em>specified</em> if it contains a <em>specified</em> element,
+ *       or it is enclosed in a <em>specified</em> element, and is <em>selected</em>.
+ *       Included elements will be documented.
+ *   </dd>
+ *
+ * </dl>
  * <p>
- * The {@code --expand-requires:value}, expands the "requires" directives of a
- * module declaration, to create a module set to considered for documentation
+ * <a name="options"></a>
+ * <h3>Options</h3>
+ * Javadoc <em>selection control</em> can be specified with these options
  * as follows:
  * <ul>
- * <li> public -- follows and expands  all "requires public" edges in the module graph
- * <li> all    -- follows and expands  all "requires" edges in the module graph.
- * By default, only the specified modules will be considered, without expansion
- * of the module dependencies.
+ *   <li>{@code --show-members:value} and {@code --show-types:value} can
+ *       be used to filter the members, with the following values:
+ *   <ul>
+ *     <li> public    -- considers only public elements
+ *     <li> protected -- considers public and protected elements
+ *     <li> package   -- considers public, protected and package private elements
+ *     <li> private   -- considers all elements
+ *   </ul>
+ *
+ *   <li>{@code --show-packages:value} "exported" or "all" can be used
+ *       to consider only exported packages or all packages within a module.
+ *
+ *   <li>{@code --show-module-contents:value} can be used to specify the level at
+ *       module declarations could be documented. A value of "api" indicates API
+ *       level documentation, and "all" indicates detailed documentation.
+ * </ul>
+ * The following options can be used to specify the elements to be documented:
+ * <ul>
+ *   <li>{@code --module} documents the specified modules.
+ *
+ *   <li>{@code --expand-requires:value} expand the set of modules to be documented
+ *        by including some or all of the modules dependencies. The value may be
+ *        one of:
+ *   <ul>
+ *     <li> public -- each module specified explicitly on the command line is
+ *          expanded to include the closure of its transitive dependencies
+ *     <li> all    -- each module specified explicitly on the command line
+ *          is expanded to include the closure of its transitive dependencies,
+ *          and also all of its direct dependencies
+ *   </ul>
+ *   By default, only the specified modules will be considered, without expansion
+ *   of the module dependencies.
+ *
+ *   <li>{@code packagenames} can be used to specify packages.
+ *   <li>{@code -subpackages} can be used to recursively load packages.
+ *   <li>{@code -exclude} can be used exclude package directories.
+ *   <li>{@code sourcefilenames} can be used to specify source file names.
  * </ul>
- * <a name="included"></a>
- * All of the above are used to select the elements, to produce the
- * <em>included</em> or the <em>selected</em> set.
- * <p>
- * {@code --show-module-contents:value} can be used to specify the level at
- * module declarations could be documented, a value of "api" indicates API
- * level documentation, and "all" indicates detailed documentation.
  * <p>
  * <a name="legacy-interactions"></a>
  * <h4>Interactions with older options.</h4>
  *
- * The new --show-* options provide a more detailed replacement for the older
- * options -public, -protected, -package, -private.  Alternatively, the older
- * options can continue to be used as shorter forms for combinations of the
- * new options, as described below:
+ * The new {@code --show-*} options provide a more detailed replacement
+ * for the older options -public, -protected, -package, -private.
+ * Alternatively, the older options can continue to be used as shorter
+ * forms for combinations of the new options, as described below:
  <table style="font-family: monospace" border=1>
     <caption>Short form options mapping</caption>
     <tr><th>Older option<th colspan="5">Equivalent to these values with the new option
-    <tr><th><th>--show-members<th>--show-types<th>--show-packages<th>--show-module-contents
-    <tr><td>-public<td>public<td>public<td>exported<td>api
-    <tr><td>-protected<td>protected<td>protected<td>exported<td>api
-    <tr><td>-package<td>package<td>package<td>all<td>all
-    <tr><td>-private<td>private<td>private<td>all<td>all
+    <tr><th><th>{@code --show-members}<th>{@code --show-types}<th>{@code --show-packages}<th>{@code --show-module-contents}
+    <tr><td>{@code -public}<td>public<td>public<td>exported<td>api
+    <tr><td>{@code -protected}<td>protected<td>protected<td>exported<td>api
+    <tr><td>{@code -package}<td>package<td>package<td>all<td>all
+    <tr><td>{@code -private}<td>private<td>private<td>all<td>all
   </table>
  * <p>
  * <a name="qualified"></a>
@@ -119,127 +152,120 @@
  * <h3>Example</h3>
  *
  * The following is an example doclet that displays information of a class
- * and its members, supporting an option "someoption".
+ * and its members, supporting an option.
  * <pre>
- * import com.sun.source.doctree.DocCommentTree;
- * import com.sun.source.util.DocTrees;
- * import java.io.IOException;
- * import java.util.Collections;
- * import java.util.Set;
- * import javax.lang.model.SourceVersion;
- * import javax.lang.model.element.Element;
- * import javax.lang.model.element.TypeElement;
- * import jdk.javadoc.doclet.*;
- *
+ * // note imports deleted for clarity
  * public class Example implements Doclet {
+ *    Reporter reporter;
+ *    &#64;Override
+ *    public void init(Locale locale, Reporter reporter) {
+ *        reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
+ *        this.reporter = reporter;
+ *    }
  *
- *     &#64;Override
- *     public void init(Locale locale, Reporter reporter) {
- *        return;
- *     }
+ *    public void printElement(DocTrees trees, Element e) {
+ *        DocCommentTree docCommentTree = trees.getDocCommentTree(e);
+ *        if (docCommentTree != null) {
+ *            System.out.println("Element (" + e.getKind() + ": "
+ *                    + e + ") has the following comments:");
+ *            System.out.println("Entire body: " + docCommentTree.getFullBody());
+ *            System.out.println("Block tags: " + docCommentTree.getBlockTags());
+ *        }
+ *    }
  *
- *     &#64;Override
- *     public boolean run(DocletEnvironment docEnv) {
- *         // cache the DocTrees utility class to access DocComments
- *         DocTrees docTrees = docEnv.getDocTrees();
+ *    &#64;Override
+ *    public boolean run(DocletEnvironment docEnv) {
+ *        reporter.print(Kind.NOTE, "overviewfile: " + overviewfile);
+ *        // get the DocTrees utility class to access document comments
+ *        DocTrees docTrees = docEnv.getDocTrees();
  *
- *         // location of an element in the same directory as overview.html
- *         try {
- *             Element barElement = null;
- *             for (Element e : docEnv.getIncludedClasses()) {
- *                 if (e.getSimpleName().toString().equals("FooBar")) {
- *                     barElement = e;
- *                 }
- *             }
- *             DocCommentTree docCommentTree =
- *                     docTrees.getDocCommentTree(barElement, "overview.html");
- *             if (docCommentTree != null) {
- *                 System.out.println("Overview html: " +
- *                         docCommentTree.getFullBody());
- *             }
- *         } catch (IOException missing) {
- *             System.err.println("No overview.html found.");
- *         }
+ *        // location of an element in the same directory as overview.html
+ *        try {
+ *            Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
+ *            DocCommentTree docCommentTree
+ *                    = docTrees.getDocCommentTree(e, overviewfile);
+ *            if (docCommentTree != null) {
+ *                System.out.println("Overview html: " + docCommentTree.getFullBody());
+ *            }
+ *        } catch (IOException missing) {
+ *            reporter.print(Kind.ERROR, "No overview.html found.");
+ *        }
  *
- *         for (TypeElement t : docEnv.getIncludedClasses()) {
- *             System.out.println(t.getKind() + ":" + t);
- *             for (Element e : t.getEnclosedElements()) {
- *                 DocCommentTree docCommentTree = docTrees.getDocCommentTree(e);
- *                 if (docCommentTree != null) {
- *                     System.out.println("Element (" + e.getKind() + ": " +
- *                             e + ") has the following comments:");
- *                     System.out.println("Entire body: " + docCommentTree.getFullBody());
- *                     System.out.println("Block tags: " + docCommentTree.getBlockTags());
- *                 } else {
- *                     System.out.println("no comment.");
- *                 }
- *             }
- *         }
- *         return true;
- *     }
+ *        for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
+ *            System.out.println(t.getKind() + ":" + t);
+ *            for (Element e : t.getEnclosedElements()) {
+ *                printElement(docTrees, e);
+ *            }
+ *        }
+ *        return true;
+ *    }
  *
- *     &#64;Override
- *     public String getName() {
- *         return "Example";
- *     }
+ *    &#64;Override
+ *    public String getName() {
+ *        return "Example";
+ *    }
  *
- *   private String someOption;
+ *    private String overviewfile;
  *
- *   &#64;Override
- *   public Set&lt;Option&gt; getSupportedOptions() {
- *       Option[] options = {
- *           new Option() {
- *               public int getArgumentCount() {
- *                   return 1;
- *               }
- *               public String getDescription() {
- *                   return "someoption";
- *               }
- *               public Option.Kind getKind() {
- *                   return Option.Kind.STANDARD;
- *               }
- *               public String getName() {
- *                   return "someoption";
- *               }
- *               public String getParameters() {
- *                   return "url";
- *               }
- *               public boolean matches(String option) {
- *                  String opt = option.startsWith("-") ? option.substring(1) : option;
- *                  return getName().equals(opt);
- *               }
- *               public boolean process(String option, ListIterator&lt;String&gt; arguments) {
- *                  overviewpath = arguments.next();
- *                  return true;
- *               }
- *          }
- *      };
- *      return new HashSet&lt;Option&gt;(Arrays.asList(options));
- *     }
+ *    &#64;Override
+ *    public Set&lt;? extends Option&gt; getSupportedOptions() {
+ *        Option[] options = {
+ *            new Option() {
+ *                private final List&lt;String&gt; someOption = Arrays.asList(
+ *                        "-overviewfile",
+ *                        "--overview-file",
+ *                        "-o"
+ *                );
  *
- *     &#64;Override
- *     public SourceVersion getSupportedSourceVersion() {
- *         // support the latest release
- *         return SourceVersion.latest();
- *     }
+ *                &#64;Override
+ *                public int getArgumentCount() {
+ *                    return 1;
+ *                }
+ *
+ *                &#64;Override
+ *                public String getDescription() {
+ *                    return "an option with aliases";
+ *                }
+ *
+ *                &#64;Override
+ *                public Option.Kind getKind() {
+ *                    return Option.Kind.STANDARD;
+ *                }
+ *
+ *                &#64;Override
+ *                public List&lt;String&gt; getNames() {
+ *                    return someOption;
+ *                }
+ *
+ *                &#64;Override
+ *                public String getParameters() {
+ *                    return "file";
+ *                }
+ *
+ *                &#64;Override
+ *                public boolean process(String opt, List&lt;String&gt; arguments) {
+ *                    overviewfile = arguments.get(0);
+ *                    return true;
+ *                }
+ *            }
+ *        };
+ *        return new HashSet&lt;&gt;(Arrays.asList(options));
+ *    }
+ *
+ *    &#64;Override
+ *    public SourceVersion getSupportedSourceVersion() {
+ *        // support the latest release
+ *        return SourceVersion.latest();
+ *    }
  * }
  * </pre>
  * <p>
- * This doclet when invoked with a command line, such as:
+ * This doclet can be invoked with a command line, such as:
  * <pre>
- *     javadoc -doclet Example -sourcepath &lt;source-location&gt;
- * </pre>
- * will produce an output, such as:
- * <pre>
- *  Overview.html: overview comments
- *  ...
- *  ...
- *  CLASS: SomeKlass
- *  .....
- *  Element (METHOD: main(java.lang.String...)) has the following comments:
- *  Entire body: The main entry point.
- *  Block tags: @param an array of Strings
- *  ...
+ *     javadoc -doclet Example &#92;
+ *       -overviewfile overview.html &#92;
+ *       -sourcepath source-location &#92;
+ *       source-location/Example.java
  * </pre>
  *
  * <h3><a name="migration">Migration Guide</a></h3>
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java
index fd6b5f17676..3880680c249 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java
@@ -54,13 +54,13 @@ public interface Taglet {
      * @return true if this <code>Taglet</code>
      * is an inline tag, false otherwise.
      */
-    public abstract boolean isInlineTag();
+    boolean isInlineTag();
 
     /**
      * Returns the name of the tag.
      * @return the name of this custom tag.
      */
-    public abstract String getName();
+    String getName();
 
     /**
      * Given the {@link DocTree DocTree} representation of this custom
@@ -69,7 +69,7 @@ public interface Taglet {
      * @param tag the <code>Tag</code> representation of this custom tag.
      * @return the string representation of this <code>Tag</code>.
      */
-    public abstract String toString(DocTree tag);
+    String toString(DocTree tag);
 
     /**
      * Given a List of {@link DocTree DocTrees} representing this custom
@@ -79,7 +79,7 @@ public interface Taglet {
      * @param tags the list of <code>DocTree</code>s representing this custom tag.
      * @return the string representation of this <code>Tag</code>.
      */
-    public abstract String toString(List<? extends DocTree> tags);
+    String toString(List<? extends DocTree> tags);
 
     /**
      * The kind of location.
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
index ac3e677f567..97cb1032a0b 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
@@ -52,6 +52,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
 
+
 /**
  * Generate class usage information.
  *
@@ -178,7 +179,7 @@ public class ClassUseWriter extends SubWriterHolderWriter {
      */
     public static void generate(ConfigurationImpl configuration, ClassTree classtree) throws DocFileIOException  {
         ClassUseMapper mapper = new ClassUseMapper(configuration, classtree);
-        for (TypeElement aClass : configuration.docEnv.getIncludedTypeElements()) {
+        for (TypeElement aClass : configuration.getIncludedTypeElements()) {
             // If -nodeprecated option is set and the containing package is marked
             // as deprecated, do not generate the class-use page. We will still generate
             // the class-use page if the class is marked as deprecated but the containing
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java
index 3485be66d24..d1f6b5fae6a 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java
@@ -288,83 +288,13 @@ public class ConfigurationImpl extends Configuration {
         if (!generalValidOptions()) {
             return false;
         }
-        boolean helpfileSeen = false;
-        // otherwise look at our options
-        for (Doclet.Option opt : optionsProcessed) {
-            if (opt.matches("-helpfile")) {
-                if (nohelp == true) {
-                    reporter.print(ERROR, getText("doclet.Option_conflict",
-                        "-helpfile", "-nohelp"));
-                    return false;
-                }
-                if (helpfileSeen) {
-                    reporter.print(ERROR, getText("doclet.Option_reuse",
-                        "-helpfile"));
-                    return false;
-                }
-                helpfileSeen = true;
-                DocFile help = DocFile.createFileForInput(this, helpfile);
-                if (!help.exists()) {
-                    reporter.print(ERROR, getText("doclet.File_not_found", helpfile));
-                    return false;
-                }
-            } else  if (opt.matches("-nohelp")) {
-                if (helpfileSeen) {
-                    reporter.print(ERROR, getText("doclet.Option_conflict",
-                        "-nohelp", "-helpfile"));
-                    return false;
-                }
-            } else if (opt.matches("-xdocrootparent")) {
-                try {
-                    URL ignored = new URL(docrootparent);
-                } catch (MalformedURLException e) {
-                    reporter.print(ERROR, getText("doclet.MalformedURL", docrootparent));
-                    return false;
-                }
-            } else if (opt.matches("-overview")) {
-                if (nooverview == true) {
-                    reporter.print(ERROR, getText("doclet.Option_conflict",
-                        "-overview", "-nooverview"));
-                    return false;
-                }
-            } else  if (opt.matches("-nooverview")) {
-                if (overviewpath != null) {
-                    reporter.print(ERROR, getText("doclet.Option_conflict",
-                        "-nooverview", "-overview"));
-                    return false;
-                }
-            } else if (opt.matches("-splitindex")) {
-                if (createindex == false) {
-                    reporter.print(ERROR, getText("doclet.Option_conflict",
-                        "-splitindex", "-noindex"));
-                    return false;
-                }
-            } else if (opt.matches("-noindex")) {
-                if (splitindex == true) {
-                    reporter.print(ERROR, getText("doclet.Option_conflict",
-                        "-noindex", "-splitindex"));
-                    return false;
-                }
-            } else if (opt.matches("-xdoclint:")) {
-                String dopt = doclintOpts.get(opt);
-                if (dopt == null) {
-                    continue;
-                }
-                if (dopt.contains("/")) {
-                    reporter.print(ERROR, getText("doclet.Option_doclint_no_qualifiers"));
-                    return false;
-                }
-                if (!DocLint.isValidOption(dopt)) {
-                    reporter.print(ERROR, getText("doclet.Option_doclint_invalid_arg"));
-                    return false;
-                }
-            } else if (opt.matches("-xdoclint/package:")) {
-                 String dopt = doclintOpts.get(opt);
-                    if (!DocLint.isValidOption(dopt)) {
-                        reporter.print(ERROR, getText("doclet.Option_doclint_package_invalid_arg"));
-                        return false;
-                    }
-                }
+        // check if helpfile exists
+        if (!helpfile.isEmpty()) {
+            DocFile help = DocFile.createFileForInput(this, helpfile);
+            if (!help.exists()) {
+                reporter.print(ERROR, getText("doclet.File_not_found", helpfile));
+                return false;
+            }
         }
         return true;
     }
@@ -374,11 +304,10 @@ public class ConfigurationImpl extends Configuration {
         if (!validateOptions()) {
             return false;
         }
-        if (!docEnv.getSpecifiedElements().isEmpty()) {
+        if (!getSpecifiedTypeElements().isEmpty()) {
             Map<String, PackageElement> map = new HashMap<>();
             PackageElement pkg;
-            List<TypeElement> classes = new ArrayList<>(docEnv.getIncludedTypeElements());
-            for (TypeElement aClass : classes) {
+            for (TypeElement aClass : getIncludedTypeElements()) {
                 pkg = utils.containingPackage(aClass);
                 if (!map.containsKey(utils.getPackageName(pkg))) {
                     map.put(utils.getPackageName(pkg), pkg);
@@ -426,7 +355,7 @@ public class ConfigurationImpl extends Configuration {
             if (showModules) {
                 topFile = DocPath.empty.resolve(DocPaths.moduleSummary(modules.first()));
             } else if (packages.size() == 1 && packages.first().isUnnamed()) {
-                List<TypeElement> classes = new ArrayList<>(docEnv.getIncludedTypeElements());
+                List<TypeElement> classes = new ArrayList<>(getIncludedTypeElements());
                 if (!classes.isEmpty()) {
                     TypeElement te = getValidClass(classes);
                     topFile = DocPath.forClass(utils, te);
@@ -450,7 +379,7 @@ public class ConfigurationImpl extends Configuration {
     }
 
     protected boolean checkForDeprecation(DocletEnvironment docEnv) {
-        for (TypeElement te : docEnv.getIncludedTypeElements()) {
+        for (TypeElement te : getIncludedTypeElements()) {
             if (isGeneratedDoc(te)) {
                 return true;
             }
@@ -597,227 +526,245 @@ public class ConfigurationImpl extends Configuration {
         Doclet.Option[] options = {
             new Option(resources, "-bottom", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    bottom = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    bottom = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-charset", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    charset = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    charset = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-doctitle", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    doctitle = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    doctitle = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-footer", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    footer = args.next();
+                public boolean process(String opt, List<String> args) {
+                    footer = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-header", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    header = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    header = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-helpfile", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    helpfile = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    if (nohelp == true) {
+                        reporter.print(ERROR, getText("doclet.Option_conflict",
+                                "-helpfile", "-nohelp"));
+                        return false;
+                    }
+                    if (!helpfile.isEmpty()) {
+                        reporter.print(ERROR, getText("doclet.Option_reuse",
+                                "-helpfile"));
+                        return false;
+                    }
+                    helpfile = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-html4") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     htmlVersion = HtmlVersion.HTML4;
                     return true;
                 }
             },
             new Option(resources, "-html5") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     htmlVersion = HtmlVersion.HTML5;
                     return true;
                 }
             },
             new Option(resources, "-nohelp") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     nohelp = true;
+                    if (!helpfile.isEmpty()) {
+                        reporter.print(ERROR, getText("doclet.Option_conflict",
+                                "-nohelp", "-helpfile"));
+                        return false;
+                    }
                     return true;
                 }
             },
             new Option(resources, "-nodeprecatedlist") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     nodeprecatedlist = true;
                     return true;
                 }
             },
             new Option(resources, "-noindex") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     createindex = false;
+                    if (splitindex == true) {
+                        reporter.print(ERROR, getText("doclet.Option_conflict",
+                                "-noindex", "-splitindex"));
+                        return false;
+                    }
                     return true;
                 }
             },
             new Option(resources, "-nonavbar") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     nonavbar = true;
                     return true;
                 }
             },
             new Hidden(resources, "-nooverview") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     nooverview = true;
+                    if (overviewpath != null) {
+                        reporter.print(ERROR, getText("doclet.Option_conflict",
+                                "-nooverview", "-overview"));
+                        return false;
+                    }
                     return true;
                 }
             },
             new Option(resources, "-notree") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     createtree = false;
                     return true;
                 }
             },
             new Option(resources, "-overview", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    overviewpath = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    overviewpath = args.get(0);
+                    if (nooverview == true) {
+                        reporter.print(ERROR, getText("doclet.Option_conflict",
+                                "-overview", "-nooverview"));
+                        return false;
+                    }
                     return true;
                 }
             },
             new Option(resources, "--frames") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     frames = true;
                     return true;
                 }
             },
             new Option(resources, "--no-frames") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     frames = false;
                     return true;
                 }
             },
             new Hidden(resources, "-packagesheader", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    packagesheader = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    packagesheader = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-splitindex") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     splitindex = true;
+                    if (createindex == false) {
+                        reporter.print(ERROR, getText("doclet.Option_conflict",
+                                "-splitindex", "-noindex"));
+                        return false;
+                    }
                     return true;
                 }
             },
             new Option(resources, "-stylesheetfile", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    stylesheetfile = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    stylesheetfile = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-top", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    top = args.next();
+                public boolean process(String opt,  List<String> args) {
+                    top = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-use") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     classuse = true;
                     return true;
                 }
             },
             new Option(resources, "-windowtitle", 1) {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    windowtitle = args.next().replaceAll("\\<.*?>", "");
+                public boolean process(String opt,  List<String> args) {
+                    windowtitle = args.get(0).replaceAll("\\<.*?>", "");
                     return true;
                 }
             },
             new XOption(resources, "-Xdoclint") {
                 @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt,  List<String> args) {
                     doclintOpts.put(this, DocLint.XMSGS_OPTION);
                     return true;
                 }
             },
             new XOption(resources, "-Xdocrootparent", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    docrootparent = args.next();
+                public boolean process(String opt, List<String> args) {
+                    docrootparent = args.get(0);
+                    try {
+                        URL ignored = new URL(docrootparent);
+                    } catch (MalformedURLException e) {
+                        reporter.print(ERROR, getText("doclet.MalformedURL", docrootparent));
+                        return false;
+                    }
                     return true;
                 }
             },
             new XOption(resources, "doclet.usage.xdoclint-extended", "-Xdoclint:", 0) {
                 @Override
-                public boolean matches(String option) {
-                    return option.toLowerCase().startsWith(getName().toLowerCase());
-                }
-
-                @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    doclintOpts.put(this, opt.replace("-Xdoclint:", DocLint.XMSGS_CUSTOM_PREFIX));
+                public boolean process(String opt,  List<String> args) {
+                    String dopt = opt.replace("-Xdoclint:", DocLint.XMSGS_CUSTOM_PREFIX);
+                    doclintOpts.put(this, dopt);
+                    if (dopt.contains("/")) {
+                        reporter.print(ERROR, getText("doclet.Option_doclint_no_qualifiers"));
+                        return false;
+                    }
+                    if (!DocLint.isValidOption(dopt)) {
+                        reporter.print(ERROR, getText("doclet.Option_doclint_invalid_arg"));
+                        return false;
+                    }
                     return true;
                 }
             },
             new XOption(resources, "doclet.usage.xdoclint-package", "-Xdoclint/package:", 0) {
                 @Override
-                public boolean matches(String option) {
-                    return option.toLowerCase().startsWith(getName().toLowerCase());
-                }
-
-                @Override
-                public boolean process(String opt,  ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    doclintOpts.put(this, opt.replace("-Xdoclint/package:", DocLint.XCHECK_PACKAGE));
+                public boolean process(String opt,  List<String> args) {
+                    String dopt = opt.replace("-Xdoclint/package:", DocLint.XCHECK_PACKAGE);
+                    doclintOpts.put(this, dopt);
+                    if (!DocLint.isValidOption(dopt)) {
+                        reporter.print(ERROR, getText("doclet.Option_doclint_package_invalid_arg"));
+                        return false;
+                    }
                     return true;
                 }
             }
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
index 3255df12f8e..d8f52ae6c12 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
@@ -91,10 +91,11 @@ public class HtmlDoclet extends AbstractDoclet {
      * Create the configuration instance.
      * Override this method to use a different
      * configuration.
-     * @return the configuration for this doclet
+     *
+     * @return the configuration
      */
     @Override // defined by AbstractDoclet
-    public ConfigurationImpl configuration() {
+    public ConfigurationImpl getConfiguration() {
         return configuration;
     }
 
@@ -166,8 +167,7 @@ public class HtmlDoclet extends AbstractDoclet {
             IndexRedirectWriter.generate(configuration);
         }
 
-        if (configuration.helpfile.length() == 0 &&
-            !configuration.nohelp) {
+        if (configuration.helpfile.isEmpty() && !configuration.nohelp) {
             HelpWriter.generate(configuration);
         }
         // If a stylesheet file is not specified, copy the default stylesheet
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
index 3467dd452e6..40019447b46 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
@@ -826,8 +826,8 @@ public class HtmlDocletWriter extends HtmlDocWriter {
      * @return a content tree for the link
      */
     protected Content getNavLinkTree() {
-        List<PackageElement> packages = new ArrayList<>(configuration.getSpecifiedPackages());
-        DocPath docPath = packages.size() == 1 && configuration.getSpecifiedClasses().isEmpty()
+        List<PackageElement> packages = new ArrayList<>(configuration.getSpecifiedPackageElements());
+        DocPath docPath = packages.size() == 1 && configuration.getSpecifiedTypeElements().isEmpty()
                 ? pathString(packages.get(0), DocPaths.PACKAGE_TREE)
                 : pathToRoot.resolve(DocPaths.OVERVIEW_TREE);
         return HtmlTree.LI(getHyperLink(docPath, contents.treeLabel, "", ""));
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java
index ed21cab1a48..eba6062dbc5 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java
@@ -32,6 +32,7 @@ import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.ElementFilter;
 
+import jdk.javadoc.doclet.DocletEnvironment;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
@@ -41,7 +42,6 @@ import jdk.javadoc.internal.doclets.toolkit.Content;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
 
-
 /**
  * Class to generate file for each module contents in the left-hand bottom
  * frame. This will list all the Class Kinds in the module. A click on any
@@ -78,9 +78,9 @@ public class ModuleFrameWriter extends HtmlDocletWriter {
     public ModuleFrameWriter(ConfigurationImpl configuration, ModuleElement moduleElement) {
         super(configuration, DocPaths.moduleTypeFrame(moduleElement));
         this.mdle = moduleElement;
-        if (configuration.getSpecifiedPackages().isEmpty()) {
+        if (configuration.getSpecifiedPackageElements().isEmpty()) {
             documentedClasses = new TreeSet<>(utils.makeGeneralPurposeComparator());
-            documentedClasses.addAll(configuration.docEnv.getIncludedTypeElements());
+            documentedClasses.addAll(configuration.getIncludedTypeElements());
         }
     }
 
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java
index 7932cda3b69..ec949e0d4c9 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java
@@ -30,6 +30,7 @@ import java.util.*;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 
+import jdk.javadoc.doclet.DocletEnvironment;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
@@ -41,7 +42,6 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
 
-
 /**
  * Class to generate file for each package contents in the left-hand bottom
  * frame. This will list all the Class Kinds in the package. A click on any
@@ -82,9 +82,9 @@ public class PackageFrameWriter extends HtmlDocletWriter {
     public PackageFrameWriter(ConfigurationImpl configuration, PackageElement packageElement) {
         super(configuration, DocPath.forPackage(packageElement).resolve(DocPaths.PACKAGE_FRAME));
         this.packageElement = packageElement;
-        if (configuration.getSpecifiedPackages().isEmpty()) {
+        if (configuration.getSpecifiedPackageElements().isEmpty()) {
             documentedClasses = new TreeSet<>(utils.makeGeneralPurposeComparator());
-            documentedClasses.addAll(configuration.docEnv.getIncludedTypeElements());
+            documentedClasses.addAll(configuration.getIncludedTypeElements());
         }
     }
 
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java
index 98b47053cbd..3ff29ee873e 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java
@@ -66,7 +66,7 @@ public class SerializedFormWriterImpl extends SubWriterHolderWriter
      */
     public SerializedFormWriterImpl(ConfigurationImpl configuration) {
         super(configuration, DocPaths.SERIALIZED_FORM);
-        visibleClasses = configuration.docEnv.getIncludedTypeElements();
+        visibleClasses = configuration.getIncludedTypeElements();
     }
 
     /**
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java
index c54eebe8e58..0a783498e65 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java
@@ -115,13 +115,13 @@ public class SourceToHTMLConverter {
         if (docEnv == null || outputdir == null) {
             return;
         }
-        for (PackageElement pkg : configuration.getSpecifiedPackages()) {
+        for (PackageElement pkg : configuration.getSpecifiedPackageElements()) {
             // If -nodeprecated option is set and the package is marked as deprecated,
             // do not convert the package files to HTML.
             if (!(configuration.nodeprecated && utils.isDeprecated(pkg)))
                 convertPackage(pkg, outputdir);
         }
-        for (TypeElement te : configuration.getSpecifiedClasses()) {
+        for (TypeElement te : configuration.getSpecifiedTypeElements()) {
             // If -nodeprecated option is set and the class is marked as deprecated
             // or the containing package is deprecated, do not convert the
             // package files to HTML.
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java
index 4d2a48e43a1..1a836d1ff24 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java
@@ -99,8 +99,8 @@ public abstract class AbstractDoclet implements Doclet {
      */
     @Override
     public boolean run(DocletEnvironment docEnv) {
-        configuration = configuration();
-        configuration.docEnv = docEnv;
+        configuration = getConfiguration();
+        configuration.initConfiguration(docEnv);
         configuration.cmtUtils = new CommentUtils(configuration);
         configuration.utils = new Utils(configuration);
         utils = configuration.utils;
@@ -171,13 +171,12 @@ public abstract class AbstractDoclet implements Doclet {
         return SourceVersion.RELEASE_9;
     }
 
-
     /**
      * Create the configuration instance and returns it.
      *
      * @return the configuration of the doclet.
      */
-    public abstract Configuration configuration();
+    public abstract Configuration getConfiguration();
 
     /**
      * Start the generation of files. Call generate methods in the individual
@@ -189,7 +188,7 @@ public abstract class AbstractDoclet implements Doclet {
      * @throws DocletException if there is a problem while generating the documentation
      */
     private void startGeneration(DocletEnvironment docEnv) throws DocletException {
-        if (docEnv.getIncludedTypeElements().isEmpty()) {
+        if (configuration.getIncludedTypeElements().isEmpty()) {
             messages.error("doclet.No_Public_Classes_To_Document");
             return;
         }
@@ -263,7 +262,7 @@ public abstract class AbstractDoclet implements Doclet {
             throws DocletException {
         generateClassFiles(classtree);
         SortedSet<PackageElement> packages = new TreeSet<>(utils.makePackageComparator());
-        packages.addAll(configuration.getSpecifiedPackages());
+        packages.addAll(configuration.getSpecifiedPackageElements());
         configuration.modulePackages.values().stream().forEach(pset -> {
             packages.addAll(pset);
         });
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java
index 3c2d2eaf4f2..7ab4c647bc1 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java
@@ -33,10 +33,13 @@ import javax.lang.model.element.ModuleElement;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.ElementFilter;
+import javax.lang.model.util.SimpleElementVisitor9;
 import javax.tools.JavaFileManager;
 import javax.tools.JavaFileObject;
 
 import com.sun.source.util.DocTreePath;
+import com.sun.tools.javac.util.DefinedBy;
+import com.sun.tools.javac.util.DefinedBy.Api;
 import jdk.javadoc.doclet.Doclet;
 import jdk.javadoc.doclet.DocletEnvironment;
 import jdk.javadoc.doclet.Reporter;
@@ -96,7 +99,7 @@ public abstract class Configuration {
     /**
      * The path to Taglets
      */
-    public String tagletpath = "";
+    public String tagletpath = null;
 
     /**
      * This is true if option "-serialwarn" is used. Defualt value is false to
@@ -312,9 +315,7 @@ public abstract class Configuration {
      */
     public SortedSet<PackageElement> packages = null;
 
-    protected final List<Doclet.Option> optionsProcessed;
-
-    public final OverviewElement overviewElement;
+    public OverviewElement overviewElement;
 
     // The following three fields provide caches for use by all instances of VisibleMemberMap.
     public final Map<TypeElement, List<Element>> propertiesCache = new HashMap<>();
@@ -336,16 +337,34 @@ public abstract class Configuration {
     protected static final String sharedResourceBundleName =
             "jdk.javadoc.internal.doclets.toolkit.resources.doclets";
     /**
-     * Constructor. Constructs the message retriever with resource file.
+     * Constructs the configurations needed by the doclet.
      */
     public Configuration() {
         excludedDocFileDirs = new HashSet<>();
         excludedQualifiers = new HashSet<>();
         setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
         metakeywords = new MetaKeywords(this);
-        optionsProcessed = new ArrayList<>();
         groups = new ArrayList<>(0);
+    }
+
+    private boolean initialized = false;
+
+    protected void initConfiguration(DocletEnvironment docEnv) {
+        if (initialized) {
+            throw new IllegalStateException("configuration previously initialized");
+        }
+        initialized = true;
+        this.docEnv = docEnv;
         overviewElement = new OverviewElement(docEnv);
+        Splitter specifiedSplitter = new Splitter(docEnv, false);
+        specifiedModuleElements = Collections.unmodifiableSet(specifiedSplitter.mset);
+        specifiedPackageElements = Collections.unmodifiableSet(specifiedSplitter.pset);
+        specifiedTypeElements = Collections.unmodifiableSet(specifiedSplitter.tset);
+
+        Splitter includedSplitter = new Splitter(docEnv, true);
+        includedModuleElements = Collections.unmodifiableSet(includedSplitter.mset);
+        includedPackageElements = Collections.unmodifiableSet(includedSplitter.pset);
+        includedTypeElements = Collections.unmodifiableSet(includedSplitter.tset);
     }
 
     /**
@@ -364,10 +383,40 @@ public abstract class Configuration {
         return this.reporter;
     }
 
+    private Set<ModuleElement> specifiedModuleElements;
+    public Set<ModuleElement> getSpecifiedModuleElements() {
+        return specifiedModuleElements;
+    }
+
+    private Set<PackageElement> specifiedPackageElements;
+    public Set<PackageElement> getSpecifiedPackageElements() {
+        return specifiedPackageElements;
+    }
+
+    private Set<TypeElement> specifiedTypeElements;
+    public Set<TypeElement> getSpecifiedTypeElements() {
+        return specifiedTypeElements;
+    }
+
+    private Set<ModuleElement> includedModuleElements;
+    public Set<ModuleElement> getIncludedModuleElements() {
+        return includedModuleElements;
+    }
+
+    private Set<PackageElement> includedPackageElements;
+    public Set<PackageElement> getIncludedPackageElements() {
+        return includedPackageElements;
+    }
+
+    private Set<TypeElement> includedTypeElements;
+    public Set<TypeElement> getIncludedTypeElements() {
+        return includedTypeElements;
+    }
+
     private void initModules() {
         // Build the modules structure used by the doclet
         modules = new TreeSet<>(utils.makeModuleComparator());
-        modules.addAll(getSpecifiedModules());
+        modules.addAll(getSpecifiedModuleElements());
 
         modulePackages = new TreeMap<>(utils.makeModuleComparator());
         for (PackageElement p: packages) {
@@ -379,7 +428,7 @@ public abstract class Configuration {
             }
         }
 
-        for (PackageElement p: docEnv.getIncludedPackageElements()) {
+        for (PackageElement p: getIncludedPackageElements()) {
             ModuleElement mdle = docEnv.getElementUtils().getModuleOf(p);
             if (mdle != null && !mdle.isUnnamed()) {
                 Set<PackageElement> s = modulePackages
@@ -398,7 +447,7 @@ public abstract class Configuration {
     private void initPackages() {
         packages = new TreeSet<>(utils.makePackageComparator());
         // add all the included packages
-        packages.addAll(docEnv.getIncludedPackageElements());
+        packages.addAll(includedPackageElements);
     }
 
     public Set<Doclet.Option> getSupportedOptions() {
@@ -406,165 +455,145 @@ public abstract class Configuration {
         Doclet.Option[] options = {
             new Option(resources, "-author") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     showauthor = true;
                     return true;
                 }
             },
             new Option(resources, "-d", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    destDirName = addTrailingFileSep(args.next());
+                public boolean process(String opt, List<String> args) {
+                    destDirName = addTrailingFileSep(args.get(0));
                     return true;
                 }
             },
             new Option(resources, "-docencoding", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    docencoding = args.next();
+                public boolean process(String opt, List<String> args) {
+                    docencoding = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-docfilessubdirs") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     copydocfilesubdirs = true;
                     return true;
                 }
             },
             new Hidden(resources, "-encoding", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    encoding = args.next();
+                public boolean process(String opt, List<String> args) {
+                    encoding = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-excludedocfilessubdir", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    addToSet(excludedDocFileDirs, args.next());
+                public boolean process(String opt, List<String> args) {
+                    addToSet(excludedDocFileDirs, args.get(0));
                     return true;
                 }
             },
             new Option(resources, "-group", 2) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    groups.add(new GroupContainer(args.next(), args.next()));
+                public boolean process(String opt, List<String> args) {
+                    groups.add(new GroupContainer(args.get(0), args.get(1)));
                     return true;
                 }
             },
             new Hidden(resources, "-javafx") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     javafx = true;
                     return true;
                 }
             },
             new Option(resources, "-keywords") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     keywords = true;
                     return true;
                 }
             },
             new Option(resources, "-link", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    urlForLink = args.next();
+                public boolean process(String opt, List<String> args) {
+                    urlForLink = args.get(0);
                     pkglistUrlForLink = urlForLink;
                     return true;
                 }
             },
             new Option(resources, "-linksource") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     linksource = true;
                     return true;
                 }
             },
             new Option(resources, "-linkoffline", 2) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    urlForLinkOffline = args.next();
-                    pkglistUrlForLinkOffline = args.next();
+                public boolean process(String opt, List<String> args) {
+                    urlForLinkOffline = args.get(0);
+                    pkglistUrlForLinkOffline = args.get(1);
                     return true;
                 }
             },
             new Option(resources, "-nocomment") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     nocomment = true;
                     return true;
                 }
             },
             new Option(resources, "-nodeprecated") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     nodeprecated = true;
                     return true;
                 }
             },
             new Option(resources, "-nosince") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     nosince = true;
                     return true;
                 }
             },
             new Option(resources, "-notimestamp") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     notimestamp = true;
                     return true;
                 }
             },
             new Option(resources, "-noqualifier", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    addToSet(excludedQualifiers, args.next());
+                public boolean process(String opt, List<String> args) {
+                    addToSet(excludedQualifiers, args.get(0));
                     return true;
                 }
             },
             new Hidden(resources, "-quiet") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     quiet = true;
                     return true;
                 }
             },
             new Option(resources, "-serialwarn") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     serialwarn = true;
                     return true;
                 }
             },
             new Option(resources, "-sourcetab", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     linksource = true;
                     try {
-                        setTabWidth(Integer.parseInt(args.next()));
+                        setTabWidth(Integer.parseInt(args.get(0)));
                     } catch (NumberFormatException e) {
                              //Set to -1 so that warning will be printed
                         //to indicate what is valid argument.
@@ -579,45 +608,41 @@ public abstract class Configuration {
             },
             new Option(resources, "-tag", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     ArrayList<String> list = new ArrayList<>();
                     list.add(opt);
-                    list.add(args.next());
+                    list.add(args.get(0));
                     customTagStrs.add(list);
                     return true;
                 }
             },
              new Option(resources, "-taglet", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     ArrayList<String> list = new ArrayList<>();
                     list.add(opt);
-                    list.add(args.next());
+                    list.add(args.get(0));
                     customTagStrs.add(list);
                     return true;
                 }
             },
             new Option(resources, "-tagletpath", 1) {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
-                    tagletpath = args.next();
+                public boolean process(String opt, List<String> args) {
+                    tagletpath = args.get(0);
                     return true;
                 }
             },
             new Option(resources, "-version") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
-                    optionsProcessed.add(this);
+                public boolean process(String opt, List<String> args) {
                     showversion = true;
                     return true;
                 }
             },
             new Hidden(resources, "--dump-on-error") {
                 @Override
-                public boolean process(String opt, ListIterator<String> args) {
+                public boolean process(String opt, List<String> args) {
                     dumpOnError = true;
                     return true;
                 }
@@ -643,7 +668,7 @@ public abstract class Configuration {
         if (docencoding == null) {
             docencoding = encoding;
         }
-        typeElementCatalog = new TypeElementCatalog(docEnv.getIncludedTypeElements(), this);
+        typeElementCatalog = new TypeElementCatalog(includedTypeElements, this);
         initTagletManager(customTagStrs);
         groups.stream().forEach((grp) -> {
             group.checkPackageGroups(grp.value1, grp.value2);
@@ -798,25 +823,19 @@ public abstract class Configuration {
     }
 
     /**
+     *
      * This checks for the validity of the options used by the user.
-     * This works exactly like DocErrorReporter. This will validate the options which are shared
-     * by our doclets. For example, this method will flag an error using
-     * the DocErrorReporter if user has used "-nohelp" and "-helpfile" option
-     * together.
+     * As of this writing, this checks only docencoding.
      *
      * @return true if all the options are valid.
      */
     public boolean generalValidOptions() {
-        boolean docencodingfound = false;
-        for (Doclet.Option opt : optionsProcessed) {
-            if (opt.matches("-docencoding")) {
-                docencodingfound = true;
-                if (!checkOutputFileEncoding(docencoding)) {
-                    return false;
-                }
+        if (docencoding != null) {
+            if (!checkOutputFileEncoding(docencoding)) {
+                return false;
             }
         }
-        if (!docencodingfound && (encoding != null && !encoding.isEmpty())) {
+        if (docencoding == null && (encoding != null && !encoding.isEmpty())) {
             if (!checkOutputFileEncoding(encoding)) {
                 return false;
             }
@@ -897,35 +916,6 @@ public abstract class Configuration {
                 : utils.getFullyQualifiedName(te);
     }
 
-    // cache these, as they are repeatedly called.
-    private Set<TypeElement> specifiedClasses = null;
-    private Set<PackageElement> specifiedPackages = null;
-    private Set<ModuleElement> specifiedModules = null;
-
-    public Set<TypeElement> getSpecifiedClasses() {
-        if (specifiedClasses == null) {
-            specifiedClasses = new LinkedHashSet<>(
-                ElementFilter.typesIn(docEnv.getSpecifiedElements()));
-        }
-        return specifiedClasses;
-    }
-
-    public Set<PackageElement> getSpecifiedPackages() {
-        if (specifiedPackages == null) {
-            specifiedPackages = new LinkedHashSet<>(
-                    ElementFilter.packagesIn(docEnv.getSpecifiedElements()));
-        }
-        return specifiedPackages;
-    }
-
-    public Set<ModuleElement> getSpecifiedModules() {
-        if (specifiedModules == null) {
-            specifiedModules = new LinkedHashSet<>(
-                    ElementFilter.modulesIn(docEnv.getSpecifiedElements()));
-        }
-        return specifiedModules;
-    }
-
     /**
      * Convenience method to obtain a resource from the doclet's
      * {@link Resources resources}.
@@ -1058,7 +1048,7 @@ public abstract class Configuration {
     public abstract boolean showMessage(Element e, String key);
 
     public static abstract class Option implements Doclet.Option, Comparable<Option> {
-        private final String name;
+        private final String[] names;
         private final String parameters;
         private final String description;
         private final int argCount;
@@ -1068,7 +1058,7 @@ public abstract class Configuration {
         }
 
         protected Option(Resources resources, String keyBase, String name, int argCount) {
-            this.name = name;
+            this.names = name.trim().split("\\s+");
             String desc = getOptionsMessage(resources, keyBase + ".description");
             if (desc.isEmpty()) {
                 this.description = "<MISSING KEY>";
@@ -1103,8 +1093,8 @@ public abstract class Configuration {
         }
 
         @Override
-        public String getName() {
-            return name;
+        public List<String> getNames() {
+            return Arrays.asList(names);
         }
 
         @Override
@@ -1114,7 +1104,7 @@ public abstract class Configuration {
 
         @Override
         public String toString() {
-            return name;
+            return names.toString();
         }
 
         @Override
@@ -1122,21 +1112,22 @@ public abstract class Configuration {
             return argCount;
         }
 
-        @Override
         public boolean matches(String option) {
-            boolean matchCase = name.startsWith("--");
-            if (option.startsWith("--") && option.contains("=")) {
-                return name.equals(option.substring(option.indexOf("=") + 1));
-            } else if (matchCase) {
-                return name.equals(option);
-            } else {
+            for (String name : names) {
+                boolean matchCase = name.startsWith("--");
+                if (option.startsWith("--") && option.contains("=")) {
+                    return name.equals(option.substring(option.indexOf("=") + 1));
+                } else if (matchCase) {
+                    return name.equals(option);
+                }
                 return name.toLowerCase().equals(option.toLowerCase());
             }
+            return false;
         }
 
         @Override
         public int compareTo(Option that) {
-            return this.getName().compareTo(that.getName());
+            return this.getNames().get(0).compareTo(that.getNames().get(0));
         }
     }
 
@@ -1187,4 +1178,54 @@ public abstract class Configuration {
             this.value2 = value2;
         }
     }
+
+    /*
+     * Splits the elements in a collection to its individual
+     * collection.
+     */
+    static private class Splitter {
+
+        final Set<ModuleElement> mset = new LinkedHashSet<>();
+        final Set<PackageElement> pset = new LinkedHashSet<>();
+        final Set<TypeElement> tset = new LinkedHashSet<>();
+
+        Splitter(DocletEnvironment docEnv, boolean included) {
+
+            Set<? extends Element> inset = included
+                    ? docEnv.getIncludedElements()
+                    : docEnv.getSpecifiedElements();
+
+            for (Element e : inset) {
+                new SimpleElementVisitor9<Void, Void>() {
+                    @Override
+                    @DefinedBy(Api.LANGUAGE_MODEL)
+                    public Void visitModule(ModuleElement e, Void p) {
+                        mset.add(e);
+                        return null;
+                    }
+
+                    @Override
+                    @DefinedBy(Api.LANGUAGE_MODEL)
+                    public Void visitPackage(PackageElement e, Void p) {
+                        pset.add(e);
+                        return null;
+                    }
+
+                    @Override
+                    @DefinedBy(Api.LANGUAGE_MODEL)
+                    public Void visitType(TypeElement e, Void p) {
+                        tset.add(e);
+                        return null;
+                    }
+
+                    @Override
+                    @DefinedBy(Api.LANGUAGE_MODEL)
+                    protected Void defaultAction(Element e, Void p) {
+                        throw new AssertionError("unexpected element: " + e);
+                    }
+
+                }.visit(e);
+            }
+        }
+    }
 }
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java
index fd29e4d3e38..74908eeffa2 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java
@@ -187,11 +187,6 @@ public class WorkArounds {
         return ((Attribute)aDesc).isSynthesized();
     }
 
-    // TODO: implement using jx.l.model
-    public boolean isVisible(TypeElement te) {
-        return ((DocEnvImpl)(configuration.docEnv)).etable.isVisible(te);
-    }
-
     // TODO: fix the caller
     public Object getConstValue(VariableElement ve) {
         return ((VarSymbol)ve).getConstValue();
@@ -286,11 +281,6 @@ public class WorkArounds {
         return null;
     }
 
-    // TODO: investigate and reimplement without javac dependencies.
-    public boolean shouldDocument(Element e) {
-        return ((DocEnvImpl)(configuration.docEnv)).etable.shouldDocument(e);
-    }
-
     // TODO: jx.l.m ?
     public Location getLocationForModule(ModuleElement mdle) {
         ModuleSymbol msym = (ModuleSymbol)mdle;
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java
index ef401f1c5d6..b19f7e665e5 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java
@@ -129,7 +129,7 @@ public class SerializedFormBuilder extends AbstractBuilder {
     @Override
     public void build() throws DocletException {
         SortedSet<TypeElement> rootclasses = new TreeSet<>(utils.makeGeneralPurposeComparator());
-        rootclasses.addAll(configuration.docEnv.getIncludedTypeElements());
+        rootclasses.addAll(configuration.getIncludedTypeElements());
         if (!serialClassFoundToDocument(rootclasses)) {
             //Nothing to document.
             return;
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java
index 0d794851c4d..92ae7cb56e2 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java
@@ -117,7 +117,7 @@ public class ClassTree {
         baseEnums = new TreeSet<>(comparator);
         baseClasses = new TreeSet<>(comparator);
         baseInterfaces = new TreeSet<>(comparator);
-        buildTree(configuration.docEnv.getIncludedTypeElements());
+        buildTree(configuration.getIncludedTypeElements());
     }
 
     /**
@@ -134,7 +134,7 @@ public class ClassTree {
         baseEnums = new TreeSet<>(comparator);
         baseClasses = new TreeSet<>(comparator);
         baseInterfaces = new TreeSet<>(comparator);
-        buildTree(configuration.docEnv.getIncludedTypeElements());
+        buildTree(configuration.getIncludedTypeElements());
     }
 
     /**
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java
index ba129673b81..2f68cc046c2 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java
@@ -206,7 +206,7 @@ public class ClassUseMapper {
             implementingClasses(intfc);
         }
         // Map methods, fields, constructors using a class.
-        Set<TypeElement> classes = docEnv.getIncludedTypeElements();
+        Set<TypeElement> classes = configuration.getIncludedTypeElements();
         for (TypeElement aClass : classes) {
             PackageElement pkg = elementUtils.getPackageOf(aClass);
             mapAnnotations(classToPackageAnnotations, pkg, pkg);
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java
index 8dc83827f8a..bdfae9fca6f 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DeprecatedAPIListBuilder.java
@@ -96,7 +96,7 @@ public class DeprecatedAPIListBuilder {
             }
         }
         deprecatedMap.put(DeprElementKind.PACKAGE, pset);
-        for (Element e : configuration.docEnv.getIncludedTypeElements()) {
+        for (Element e : configuration.getIncludedTypeElements()) {
             TypeElement te = (TypeElement)e;
             SortedSet<Element> eset;
             if (utils.isDeprecated(e)) {
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java
index 6d501000b81..454cc8fad17 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java
@@ -126,8 +126,8 @@ public class IndexBuilder {
      * @param docEnv the doclet environment
      */
     protected void buildIndexMap(DocletEnvironment docEnv)  {
-        Set<PackageElement> packages = configuration.getSpecifiedPackages();
-        Set<TypeElement> classes = docEnv.getIncludedTypeElements();
+        Set<PackageElement> packages = configuration.getSpecifiedPackageElements();
+        Set<TypeElement> classes = configuration.getIncludedTypeElements();
         if (!classesOnly) {
             if (packages.isEmpty()) {
                 Set<PackageElement> set = new HashSet<>();
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
index 7ba231bac15..d0687ece1f6 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
@@ -2263,22 +2263,22 @@ public class Utils {
     private List<TypeElement> getInnerClasses(Element e, boolean filter) {
         List<TypeElement> olist = new ArrayList<>();
         for (TypeElement te : getClassesUnfiltered(e)) {
-            if (!filter || configuration.workArounds.isVisible(te)) {
+            if (!filter || configuration.docEnv.isSelected(te)) {
                 olist.add(te);
             }
         }
         for (TypeElement te : getInterfacesUnfiltered(e)) {
-            if (!filter || configuration.workArounds.isVisible(te)) {
+            if (!filter || configuration.docEnv.isSelected(te)) {
                 olist.add(te);
             }
         }
         for (TypeElement te : getAnnotationTypesUnfiltered(e)) {
-            if (!filter || configuration.workArounds.isVisible(te)) {
+            if (!filter || configuration.docEnv.isSelected(te)) {
                 olist.add(te);
             }
         }
         for (TypeElement te : getEnumsUnfiltered(e)) {
-            if (!filter || configuration.workArounds.isVisible(te)) {
+            if (!filter || configuration.docEnv.isSelected(te)) {
                 olist.add(te);
             }
         }
@@ -2361,7 +2361,7 @@ public class Utils {
         List<Element> elements = new ArrayList<>();
         for (Element e : te.getEnclosedElements()) {
             if (kinds.contains(e.getKind())) {
-                if (!filter || configuration.workArounds.shouldDocument(e)) {
+                if (!filter || shouldDocument(e)) {
                     elements.add(e);
                 }
             }
@@ -2369,6 +2369,36 @@ public class Utils {
         return elements;
     }
 
+    private SimpleElementVisitor9<Boolean, Void> shouldDocumentVisitor = null;
+    private boolean shouldDocument(Element e) {
+        if (shouldDocumentVisitor == null) {
+            shouldDocumentVisitor = new SimpleElementVisitor9<Boolean, Void>() {
+                private boolean hasSource(TypeElement e) {
+                    return configuration.docEnv.getFileKind(e) ==
+                            javax.tools.JavaFileObject.Kind.SOURCE;
+                }
+
+                // handle types
+                @Override
+                public Boolean visitType(TypeElement e, Void p) {
+                    return configuration.docEnv.isSelected(e) && hasSource(e);
+                }
+
+                // handle everything else
+                @Override
+                protected Boolean defaultAction(Element e, Void p) {
+                    return configuration.docEnv.isSelected(e);
+                }
+
+                @Override
+                public Boolean visitUnknown(Element e, Void p) {
+                    throw new AssertionError("unkown element: " + p);
+                }
+            };
+        }
+        return shouldDocumentVisitor.visit(e);
+    }
+
     /*
      * nameCache is maintained for improving the comparator
      * performance, noting that the Collator used by the comparators
@@ -2578,17 +2608,17 @@ public class Utils {
             specifiedVisitor = new SimpleElementVisitor9<Boolean, Void>() {
                 @Override
                 public Boolean visitModule(ModuleElement e, Void p) {
-                    return configuration.getSpecifiedModules().contains(e);
+                    return configuration.getSpecifiedModuleElements().contains(e);
                 }
 
                 @Override
                 public Boolean visitPackage(PackageElement e, Void p) {
-                    return configuration.getSpecifiedPackages().contains(e);
+                    return configuration.getSpecifiedPackageElements().contains(e);
                 }
 
                 @Override
                 public Boolean visitType(TypeElement e, Void p) {
-                    return configuration.getSpecifiedClasses().contains(e);
+                    return configuration.getSpecifiedTypeElements().contains(e);
                 }
 
                 @Override
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/DocEnvImpl.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/DocEnvImpl.java
index 3612ef3fe47..01fa6bbcf08 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/DocEnvImpl.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/DocEnvImpl.java
@@ -25,19 +25,15 @@
 
 package jdk.javadoc.internal.tool;
 
-import java.util.LinkedHashSet;
-import java.util.List;
 import java.util.Set;
-import java.util.stream.Collectors;
 
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.Element;
-import javax.lang.model.element.ModuleElement;
-import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.Elements;
 import javax.lang.model.util.Types;
 import javax.tools.JavaFileManager;
+import javax.tools.JavaFileObject.Kind;
 
 import com.sun.source.util.DocTrees;
 import com.sun.tools.javac.code.Source;
@@ -74,24 +70,14 @@ public class DocEnvImpl implements DocletEnvironment {
         this.toolEnv = toolEnv;
         this.etable = etable;
     }
-
-    @Override
-    public Set<ModuleElement> getIncludedModuleElements() {
-        return etable.getIncludedModuleElements();
+   @Override
+    public Set<? extends Element> getSpecifiedElements() {
+        return etable.getSpecifiedElements();
     }
 
     @Override
-    public Set<PackageElement> getIncludedPackageElements() {
-        return etable.getIncludedPackageElements();
-    }
-
-    /**
-     * Return all TypeElements (including those inside
-     * packages) to be documented.
-     */
-    @Override
-    public Set<TypeElement> getIncludedTypeElements() {
-        return etable.getIncludedTypeElements();
+    public Set<? extends Element> getIncludedElements() {
+        return etable.getIncludedElements();
     }
 
     @Override
@@ -109,22 +95,6 @@ public class DocEnvImpl implements DocletEnvironment {
         return toolEnv.elements;
     }
 
-    @Override
-    public List<Element> getSelectedElements(List<? extends Element> elements) {
-        return elements.stream()
-                .filter(e -> isIncluded(e))
-                .collect(Collectors.<Element>toList());
-    }
-
-    @Override
-    public Set<Element> getSpecifiedElements() {
-        Set<Element> out = new LinkedHashSet<>();
-        out.addAll(etable.getSpecifiedModuleElements());
-        out.addAll(etable.getSpecifiedPackageElements());
-        out.addAll(etable.getSpecifiedTypeElements());
-        return out;
-    }
-
     @Override
     public Types getTypeUtils() {
         return toolEnv.typeutils;
@@ -144,4 +114,14 @@ public class DocEnvImpl implements DocletEnvironment {
     public ModuleMode getModuleMode() {
         return etable.getModuleMode();
     }
+
+    @Override
+    public Kind getFileKind(TypeElement type) {
+        return toolEnv.getFileKind(type);
+    }
+
+    @Override
+    public boolean isSelected(Element e) {
+        return etable.isSelected(e);
+    }
 }
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java
index 82f07f1ad06..ab34330619e 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java
@@ -137,7 +137,7 @@ import static jdk.javadoc.internal.tool.JavadocTool.isValidClassName;
  * Rules for processing:
  *
  * 1. A specified element, meaning an element given on the
- *    command-line, and exposed via getSpecifiedElements()
+ *    command-line, and exposed via specified elements collections.
  * 2. Expand-contents, an internal pseudo term, meaning
  *    it is part of the recursive expansion of specified
  *    elements, meaning, the modules are expanded first, then
@@ -230,8 +230,28 @@ public class ElementsTable {
         }
     }
 
+    private Set<Element> specifiedElements = null;
     /**
-     * Returns the selected/included module elements.
+     * Returns a set of elements specified on the
+     * command line, including any inner classes.
+     *
+     * @return the set of elements specified on the command line
+     */
+    public Set<? extends Element> getSpecifiedElements() {
+        if (specifiedElements == null) {
+            Set<Element> result = new LinkedHashSet<>();
+            result.addAll(specifiedModuleElements);
+            result.addAll(specifiedPackageElements);
+            result.addAll(specifiedTypeElements);
+            specifiedElements = Collections.unmodifiableSet(result);
+        }
+        return specifiedElements;
+    }
+
+    private Set<Element> includedElements = null;
+    /**
+     * Returns a set of elements included elements. The inclusion is as
+     * follows:
      * A module is fully included,
      *   - is specified on the command line --module
      *   - is derived from the module graph, that is, by expanding the
@@ -239,14 +259,7 @@ public class ElementsTable {
      *
      * A module is included if an enclosed package or type is
      * specified on the command line.
-     * @return the included module elements
-     */
-    public Set<ModuleElement> getIncludedModuleElements() {
-        return includedModuleElements;
-    }
-
-    /**
-     * Returns the selected/included package elements.
+     *
      * A package is fully included,
      *  - is specified on the command line
      *  - is derived from expanding -subpackages
@@ -255,66 +268,32 @@ public class ElementsTable {
      * A package is included, if an enclosed package or a type is specified on
      * the command line.
      *
-     * @return the included package elements
-     */
-    public Set<PackageElement> getIncludedPackageElements() {
-        return includedPackageElements;
-    }
-
-    /**
-     * Returns the selected/included type elements (including those
-     * within specified or included packages) to be documented.
+     * Included type elements (including those within specified or included packages)
+     * to be documented.
+     *
      * A type is fully included if
      *  - is specified on the command line with -sourcepath
      *  - is visible with --show-types filter
      * A nested type is fully included if
      *  - is visible with --show-types filter
      *  - is enclosed in a fully included type
-     *
-     * @return the included type elements
-     * to be documented
+     * @return the set of elements specified on the command line
      */
-    public Set<TypeElement> getIncludedTypeElements() {
-        return includedTypeElements;
-    }
-
-    /**
-     * Returns a set of module elements specified on the
-     * command line.
-     * @return the set of module elements specified on the
-     * command line
-     */
-    public Set<ModuleElement> getSpecifiedModuleElements() {
-        return specifiedModuleElements;
-    }
-
-    /**
-     * Returns a set of package elements specified on the
-     * command line. These may also contain children packages
-     * if specified with -subpackage.
-     *
-     * @return the set of package elements specified on the
-     * command line
-     */
-    public Set<PackageElement> getSpecifiedPackageElements() {
-        return specifiedPackageElements;
-    }
-
-    /**
-     * Returns a set of type elements specified on the
-     * command line, including any inner classes.
-     *
-     * @return the set of type elements specified on the command line
-     */
-    public Set<TypeElement> getSpecifiedTypeElements() {
-        return specifiedTypeElements;
+    public Set<? extends Element> getIncludedElements() {
+        if (includedElements == null) {
+            Set<Element> result = new LinkedHashSet<>();
+            result.addAll(includedModuleElements);
+            result.addAll(includedPackageElements);
+            result.addAll(includedTypeElements);
+            includedElements = Collections.unmodifiableSet(result);
+        }
+        return includedElements;
     }
 
     private IncludedVisitor includedVisitor = null;
 
     /**
-     * Returns true if the given element is included or selected for
-     * consideration.
+     * Returns true if the given element is included for consideration.
      * This method accumulates elements in the cache as enclosed elements of
      * fully included elements are tested.
      * A member (constructor, method, field) is included if
@@ -539,7 +518,7 @@ public class ElementsTable {
         ListBuffer<ModuleElement> queue = new ListBuffer<>();
 
         // expand each specified module
-        for (ModuleElement mdle : getSpecifiedModuleElements()) {
+        for (ModuleElement mdle : specifiedModuleElements) {
             result.add(mdle); // a specified module is included
             queue.append(mdle);
             Set<ModuleElement> publicRequires = getModuleRequires(mdle, true);
@@ -700,7 +679,7 @@ public class ElementsTable {
      */
     private void computeSpecifiedTypes() throws ToolException {
         Set<TypeElement> classes = new LinkedHashSet<>();
-        classDecList.stream().filter((def) -> (shouldDocument(def.sym))).forEach((def) -> {
+          classDecList.forEach((def) -> {
             TypeElement te = (TypeElement) def.sym;
             if (te != null) {
                 addAllClasses(classes, te, true);
@@ -853,17 +832,14 @@ public class ElementsTable {
         try {
             // eliminate needless checking, do this first.
             if (list.contains(klass)) return;
-            if (toolEnv.isSynthetic(klass)) return;
             // ignore classes with invalid Java class names
             if (!JavadocTool.isValidClassName(klass.name.toString())) return;
-            if (filtered && !shouldDocument(klass)) return;
+            if (filtered && !isTypeElementSelected(klass)) return;
             list.add(klass);
             for (Symbol sym : klass.members().getSymbols(NON_RECURSIVE)) {
                 if (sym != null && sym.kind == Kind.TYP) {
                     ClassSymbol s = (ClassSymbol)sym;
-                    if (!toolEnv.isSynthetic(s)) {
-                        addAllClasses(list, s, filtered);
-                    }
+                    addAllClasses(list, s, filtered);
                 }
             }
         } catch (CompletionFailure e) {
@@ -882,92 +858,65 @@ public class ElementsTable {
         boolean filtered = true;
         PackageSymbol sym = (PackageSymbol)pkg;
         for (Symbol isym : sym.members().getSymbols(NON_RECURSIVE)) {
-            if (isym != null) {
-                ClassSymbol s = (ClassSymbol)isym;
-                if (!toolEnv.isSynthetic(sym)) {
-                    addAllClasses(list, s, filtered);
-                }
-            }
+            addAllClasses(list, (TypeElement)isym, filtered);
         }
     }
 
-    SimpleElementVisitor9<Boolean, Void> shouldDocumentVisitor = null;
-    /**
-     * Returns whether an element ought to be documented.
-     * @param e the element in question
-     * @return true if the element should be documented
-     */
-    public boolean shouldDocument(Element e) {
-        if (shouldDocumentVisitor == null) {
-            shouldDocumentVisitor = new SimpleElementVisitor9<Boolean, Void>() {
+    private boolean isTypeElementSelected(TypeElement te) {
+        return (xclasses || toolEnv.isFromSource(te)) && isSelected(te);
+    }
 
+    SimpleElementVisitor9<Boolean, Void> visibleElementVisitor = null;
+    /**
+     * Returns true if the element is selected, by applying
+     * the access filter checks. Special treatment is applied to
+     * types, for a top level type the access filter applies completely,
+     * however if is a nested type then it is allowed either  if
+     * the enclosing is a static or the enclosing is also selected.
+     *
+     * @param e the element to be checked
+     * @return true if the element is visible
+     */
+    public boolean isSelected(Element e) {
+        if (toolEnv.isSynthetic((Symbol) e)) {
+            return false;
+        }
+        if (visibleElementVisitor == null) {
+            visibleElementVisitor = new SimpleElementVisitor9<Boolean, Void>() {
                 @Override
                 public Boolean visitType(TypeElement e, Void p) {
-                    return shouldDocument((ClassSymbol) e);
+                    if (!accessFilter.checkModifier(e)) {
+                        return false; // it is not allowed
+                    }
+                    Element encl = e.getEnclosingElement();
+
+                    // check if nested
+                    if (encl.getKind() == ElementKind.PACKAGE)
+                        return true; // top-level class, allow it
+
+                    // is enclosed static
+                    if (encl.getModifiers().contains(Modifier.STATIC))
+                        return true; // allowed
+
+                    // check the enclosing
+                    return visit(encl);
                 }
 
                 @Override
-                public Boolean visitVariable(VariableElement e, Void p) {
-                    return shouldDocument((VarSymbol) e);
-                }
-
-                @Override
-                public Boolean visitExecutable(ExecutableElement e, Void p) {
-                    return shouldDocument((MethodSymbol) e);
-                }
-
-                @Override
-                public Boolean visitPackage(PackageElement e, Void p) {
+                protected Boolean defaultAction(Element e, Void p) {
                     return accessFilter.checkModifier(e);
                 }
+
+                @Override
+                public Boolean visitUnknown(Element e, Void p) {
+                    throw new AssertionError("unkown element: " + p);
+                }
             };
         }
-        return shouldDocumentVisitor.visit(e);
-    }
-
-    /** Check whether this member should be documented. */
-    private boolean shouldDocument(VarSymbol sym) {
-        if (toolEnv.isSynthetic(sym)) {
-            return false;
-        }
-        return accessFilter.checkModifier(sym);
-    }
-
-    /** Check whether this member should be documented. */
-    private boolean shouldDocument(MethodSymbol sym) {
-        if (toolEnv.isSynthetic(sym)) {
-            return false;
-        }
-        return accessFilter.checkModifier(sym);
-    }
-
-    /** Check whether this class should be documented. */
-    private boolean shouldDocument(ClassSymbol sym) {
-        return
-            !toolEnv.isSynthetic(sym) && // no synthetics
-            (xclasses || toolEnv.hasPath(sym)) &&
-            isVisible(sym);
-    }
-
-    /**
-     * Returns the visibility of a type element.
-     * If the type element is a nested type, then check if the
-     * enclosing is static or the enclosed is visible.
-     *
-     * @param te the type element to be checked
-     * @return true if the element is visible
-     */
-    public boolean isVisible(TypeElement te) {
-        ClassSymbol sym = (ClassSymbol)te;
-        if (!accessFilter.checkModifier(sym)) {
-            return false;
-        }
-        ClassSymbol encl = sym.owner.enclClass();
-        return (encl == null || (sym.flags_field & Flags.STATIC) != 0 || isVisible(encl));
+        return visibleElementVisitor.visit(e);
     }
 
     private class IncludedVisitor extends SimpleElementVisitor9<Boolean, Void> {
-
         final private Set<Element> includedCache;
 
         public IncludedVisitor() {
@@ -991,7 +940,7 @@ public class ElementsTable {
             if (includedTypeElements.contains(e)) {
                 return true;
             }
-            if (shouldDocument(e)) {
+            if (isTypeElementSelected(e)) {
                 // Class is nameable from top-level and
                 // the class and all enclosing classes
                 // pass the modifier filter.
@@ -1019,7 +968,7 @@ public class ElementsTable {
         public Boolean defaultAction(Element e, Void p) {
             if (includedCache.contains(e))
                 return true;
-            if (visit(e.getEnclosingElement()) && shouldDocument(e)) {
+            if (visit(e.getEnclosingElement()) && isSelected(e)) {
                 switch(e.getKind()) {
                     case ANNOTATION_TYPE: case CLASS: case ENUM: case INTERFACE:
                     case MODULE: case OTHER: case PACKAGE:
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocEnter.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocEnter.java
index 394a0c60324..77a1630cd3c 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocEnter.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocEnter.java
@@ -99,6 +99,7 @@ public class JavadocEnter extends Enter {
         if (tree.sym.kind == TYP || tree.sym.kind == ERR) {
             ClassSymbol c = tree.sym;
             toolEnv.setElementToTreePath(c, toolEnv.getTreePath(env.toplevel, tree));
+            c.classfile = env.toplevel.sourcefile;
         }
     }
 
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java
index c3e14596c97..b5512a22bb0 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java
@@ -62,6 +62,7 @@ import com.sun.tools.javac.util.Context;
 import com.sun.tools.javac.util.Log;
 import com.sun.tools.javac.util.Log.WriterKind;
 import com.sun.tools.javac.util.Options;
+import com.sun.tools.javac.util.StringUtils;
 
 import jdk.javadoc.doclet.Doclet;
 import jdk.javadoc.doclet.Doclet.Option;
@@ -233,7 +234,7 @@ public class Start extends ToolOption.Helper {
 
             @Override
             public int compare(Doclet.Option o1, Doclet.Option o2) {
-                return collator.compare(o1.getName(), o2.getName());
+                return collator.compare(o1.getNames().get(0), o2.getNames().get(0));
             }
         };
 
@@ -244,10 +245,11 @@ public class Start extends ToolOption.Helper {
     }
 
     void showDocletOption(Doclet.Option option) {
-        List<String> names = Arrays.asList(option.getName());
+        List<String> names = option.getNames();
         String parameters;
-        if (option.getArgumentCount() > 0 || option.getName().endsWith(":")) {
-            String sep = option.getName().endsWith(":") ? "" : " ";
+        String optname = names.get(0);
+        if (option.getArgumentCount() > 0 || optname.endsWith(":")) {
+            String sep = optname.endsWith(":") ? "" : " ";
             parameters = sep + option.getParameters();
         } else {
             parameters = "";
@@ -610,7 +612,23 @@ public class Start extends ToolOption.Helper {
         return ok;
     }
 
-    Set<Doclet.Option> docletOptions = null;
+    boolean matches(List<String> names, String arg) {
+        for (String name : names) {
+            if (StringUtils.toLowerCase(name).equals(StringUtils.toLowerCase(arg)))
+                return true;
+        }
+        return false;
+    }
+
+    boolean matches(Doclet.Option option, String arg) {
+        if (matches(option.getNames(), arg))
+             return true;
+        int sep = arg.indexOf(':');
+        String targ = arg.substring(0, sep + 1);
+        return matches(option.getNames(), targ);
+    }
+
+    Set<? extends Doclet.Option> docletOptions = null;
     int handleDocletOptions(int idx, List<String> args, boolean isToolOption)
             throws OptionException {
         if (docletOptions == null) {
@@ -628,14 +646,14 @@ public class Start extends ToolOption.Helper {
         }
         String text = null;
         for (Doclet.Option opt : docletOptions) {
-            if (opt.matches(argBase)) {
+            if (matches(opt, argBase)) {
                 if (argVal != null) {
                     switch (opt.getArgumentCount()) {
                         case 0:
                             text = messager.getText("main.unnecessary_arg_provided", argBase);
                             throw new OptionException(ERROR, this::usage, text);
                         case 1:
-                            opt.process(arg, Arrays.asList(argVal).listIterator());
+                            opt.process(arg, Arrays.asList(argVal));
                             break;
                         default:
                             text = messager.getText("main.only_one_argument_with_equals", argBase);
@@ -646,7 +664,7 @@ public class Start extends ToolOption.Helper {
                         text = messager.getText("main.requires_argument", arg);
                         throw new OptionException(ERROR, this::usage, text);
                     }
-                    opt.process(arg, args.listIterator(idx + 1));
+                    opt.process(arg, args.subList(idx + 1, args.size()));
                     idx += opt.getArgumentCount();
                 }
                 return idx;
diff --git a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java
index 3cdf46730a6..31719c60725 100644
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java
@@ -34,6 +34,7 @@ import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.Elements;
 import javax.tools.JavaFileManager;
 import javax.tools.JavaFileObject;
+import javax.tools.JavaFileObject.Kind;
 
 import com.sun.source.util.DocTrees;
 import com.sun.source.util.TreePath;
@@ -193,17 +194,20 @@ public class ToolEnvironment {
     }
 
     /**
-     * Returns true if the symbol has a tree path associated with it.
-     * Primarily used to disambiguate a symbol associated with a source
+     * Returns true if the type element originates from source.
+     * Primarily used to disambiguate a type element associated with a source
      * file versus a class file.
-     * @param sym the symbol to be checked
-     * @return true if the symbol has a tree path
+     * @param te the type element
+     * @return true if the symbol is from source
      */
-    boolean hasPath(ClassSymbol sym) {
-        TreePath path = elementToTreePath.get(sym);
-        return path != null;
+    public boolean isFromSource(TypeElement te) {
+        return getFileKind(te) == Kind.SOURCE;
     }
 
+    public Kind getFileKind(TypeElement te) {
+        JavaFileObject jfo = ((ClassSymbol)te).outermostClass().classfile;
+        return jfo == null ? Kind.SOURCE : jfo.getKind();
+    }
     /**
      * Print a notice, iff <em>quiet</em> is not specified.
      *
diff --git a/langtools/test/jdk/javadoc/doclet/testBaseClass/BaseClass.java b/langtools/test/jdk/javadoc/doclet/testBaseClass/BaseClass.java
index 479939ad54b..87a749665be 100644
--- a/langtools/test/jdk/javadoc/doclet/testBaseClass/BaseClass.java
+++ b/langtools/test/jdk/javadoc/doclet/testBaseClass/BaseClass.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,14 +39,18 @@
  */
 
 import java.util.Collections;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Set;
+import java.util.stream.Collectors;
+
 import javax.lang.model.SourceVersion;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ElementKind;
 import javax.lang.model.element.TypeElement;
+import javax.lang.model.util.ElementFilter;
 import javax.lang.model.util.Elements;
 
 import jdk.javadoc.doclet.*;
@@ -60,17 +64,17 @@ public class BaseClass implements Doclet {
             throw new AssertionError("Base class is not included: baz.Foo");
         }
 
-        for (Element e : root.getSpecifiedElements()) {
-            if (e.getKind() == ElementKind.CLASS &&
-                    e.getSimpleName().contentEquals("Bar")) {
-                klass = (TypeElement)e;
+        for (TypeElement te : ElementFilter.typesIn(root.getSpecifiedElements())) {
+            if (te.getKind() == ElementKind.CLASS &&
+                    te.getSimpleName().contentEquals("Bar")) {
+                klass = te;
             }
         }
         if (klass == null) {
             throw new AssertionError("class Bar not found");
         }
         List<? extends Element> members = klass.getEnclosedElements();
-        List<Element> selected = root.getSelectedElements(members);
+
 
         boolean foundPublic = false;
         boolean foundProtected = false;
@@ -78,8 +82,11 @@ public class BaseClass implements Doclet {
         boolean foundPackagePrivate = false;
         boolean foundPrivate = false;
 
+        List<Element> included = members.stream()
+                .filter(cls -> root.isIncluded(cls))
+                .collect(Collectors.toList());
 
-        for (Element e :selected) {
+        for (Element e : included) {
             System.out.println("element: " + e);
             if (e.getSimpleName().toString().equals("aPublicMethod")) {
                 foundPublic = true;
diff --git a/langtools/test/jdk/javadoc/tool/6227454/Test.java b/langtools/test/jdk/javadoc/tool/6227454/Test.java
index e2afa8b38d9..2dd19eeec00 100644
--- a/langtools/test/jdk/javadoc/tool/6227454/Test.java
+++ b/langtools/test/jdk/javadoc/tool/6227454/Test.java
@@ -25,19 +25,21 @@
  * @test
  * @bug 6227454
  * @summary package.html and overview.html may not be read fully
- *  * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
  */
 
 import java.io.*;
+import java.util.ArrayList;
 import java.util.Arrays;
 
 import java.util.HashSet;
-import java.util.ListIterator;
+import java.util.List;
 import java.util.Locale;
 import java.util.Set;
 
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.Element;
+import javax.lang.model.util.ElementFilter;
 
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.util.DocTrees;
@@ -45,7 +47,6 @@ import jdk.javadoc.doclet.Doclet;
 import jdk.javadoc.doclet.Reporter;
 import jdk.javadoc.doclet.DocletEnvironment;
 
-
 public class Test implements Doclet {
     public static void main(String... args) throws Exception {
         new Test().run();
@@ -140,9 +141,9 @@ public class Test implements Doclet {
 
     public boolean run(DocletEnvironment root) {
         DocTrees docTrees = root.getDocTrees();
-        System.out.println("classes:" + root.getIncludedTypeElements());
+        System.out.println("classes:" + ElementFilter.typesIn(root.getIncludedElements()));
 
-        Element klass = root.getIncludedTypeElements().iterator().next();
+        Element klass = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
         String text = "";
         try {
             DocCommentTree dcTree = docTrees.getDocCommentTree(klass, overviewpath);
@@ -190,8 +191,10 @@ public class Test implements Doclet {
                 }
 
                 @Override
-                public String getName() {
-                    return "overview";
+                public List<String> getNames() {
+                    List<String> out = new ArrayList<>();
+                    out.add("overview");
+                    return out;
                 }
 
                 @Override
@@ -200,21 +203,13 @@ public class Test implements Doclet {
                 }
 
                 @Override
-                public boolean matches(String option) {
-                    String opt = option.startsWith("-") ? option.substring(1) : option;
-                    return getName().equals(opt);
-                }
-
-                @Override
-                public boolean process(String option, ListIterator<String> arguments) {
-                    if (matches(option)) {
-                        overviewpath = arguments.next();
-                    }
+                public boolean process(String option, List<String> arguments) {
+                    overviewpath = arguments.get(0);
                     return true;
                 }
             }
         };
-        return new HashSet<Option>(Arrays.asList(options));
+        return new HashSet<>(Arrays.asList(options));
     }
 
     @Override
diff --git a/langtools/test/jdk/javadoc/tool/BreakIteratorWarning.java b/langtools/test/jdk/javadoc/tool/BreakIteratorWarning.java
index 50d90bc0876..44e446f8166 100644
--- a/langtools/test/jdk/javadoc/tool/BreakIteratorWarning.java
+++ b/langtools/test/jdk/javadoc/tool/BreakIteratorWarning.java
@@ -40,6 +40,7 @@ import javax.lang.model.SourceVersion;
 import javax.lang.model.element.ElementKind;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.element.VariableElement;
+import javax.lang.model.util.ElementFilter;
 
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.doctree.DocTree;
@@ -75,7 +76,7 @@ public class BreakIteratorWarning implements Doclet {
     }
 
     public boolean run(DocletEnvironment root) {
-        TypeElement cd = root.getIncludedTypeElements().iterator().next();
+        TypeElement cd = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
         VariableElement fd = getFields(cd).get(0);
         DocTrees docTrees = root.getDocTrees();
         DocCommentTree docCommentTree = docTrees.getDocCommentTree(fd);
diff --git a/langtools/test/jdk/javadoc/tool/InlineTagsWithBraces.java b/langtools/test/jdk/javadoc/tool/InlineTagsWithBraces.java
index 73837c03395..1670d257710 100644
--- a/langtools/test/jdk/javadoc/tool/InlineTagsWithBraces.java
+++ b/langtools/test/jdk/javadoc/tool/InlineTagsWithBraces.java
@@ -80,7 +80,7 @@ public class InlineTagsWithBraces implements Doclet {
 
     public boolean run(DocletEnvironment root) {
         DocTrees trees = root.getDocTrees();
-        TypeElement cd = root.getIncludedTypeElements().iterator().next();
+        TypeElement cd = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
         DocCommentTree docCommentTree = trees.getDocCommentTree(cd);
         List<? extends DocTree> tags = docCommentTree.getBody();
 
diff --git a/langtools/test/jdk/javadoc/tool/NoStar.java b/langtools/test/jdk/javadoc/tool/NoStar.java
index 041fb208c5a..49ee9c8ee39 100644
--- a/langtools/test/jdk/javadoc/tool/NoStar.java
+++ b/langtools/test/jdk/javadoc/tool/NoStar.java
@@ -34,6 +34,7 @@ import java.util.*;
 
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.TypeElement;
+import javax.lang.model.util.ElementFilter;
 
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.util.DocTrees;
@@ -62,7 +63,7 @@ public class NoStar implements Doclet
     }
 
     public boolean run(DocletEnvironment root) {
-        Set<TypeElement> classes = root.getIncludedTypeElements();
+        Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
         if (classes.size() != 1)
             throw new Error("1 " + Arrays.asList(classes));
         TypeElement self = classes.iterator().next();
diff --git a/langtools/test/jdk/javadoc/tool/OptionSyntaxTest.java b/langtools/test/jdk/javadoc/tool/OptionSyntaxTest.java
index 6a0eb8b1be9..f37bc8b6ffa 100644
--- a/langtools/test/jdk/javadoc/tool/OptionSyntaxTest.java
+++ b/langtools/test/jdk/javadoc/tool/OptionSyntaxTest.java
@@ -40,9 +40,7 @@ import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashSet;
 import java.util.List;
-import java.util.ListIterator;
 import java.util.Locale;
-import java.util.Objects;
 import java.util.Set;
 
 import javax.lang.model.SourceVersion;
@@ -97,11 +95,11 @@ public class OptionSyntaxTest extends TestRunner {
     }
 
     static class DOption implements Doclet.Option {
-        private final String name;
+        private final List<String> names = new ArrayList<>();
         private final int argCount;
 
         DOption(String name, int argCount) {
-            this.name = name;
+            this.names.add(name);
             this.argCount = argCount;
         }
 
@@ -112,7 +110,7 @@ public class OptionSyntaxTest extends TestRunner {
 
         @Override
         public String getDescription() {
-            return "description[" + name + "]";
+            return "description[" + names.get(0) + "]";
         }
 
         @Override
@@ -121,25 +119,20 @@ public class OptionSyntaxTest extends TestRunner {
         }
 
         @Override
-        public String getName() {
-            return name;
+        public List<String> getNames() {
+            return names;
         }
 
         @Override
         public String getParameters() {
-            return argCount > 0 ? "parameters[" + name + "," + argCount + "]" : null;
+            return argCount > 0 ? "parameters[" + names.get(0) + "," + argCount + "]" : null;
         }
 
         @Override
-        public boolean matches(String option) {
-            return option.equals(name);
-        }
-
-        @Override
-        public boolean process(String option, ListIterator<String> arguments) {
+        public boolean process(String option, List<String> arguments) {
             List<String> args = new ArrayList<>();
-            for (int i = 0; i < argCount && arguments.hasNext(); i++) {
-                args.add(arguments.next());
+            for (int i = 0; i < argCount && i < arguments.size(); i++) {
+                args.add(arguments.get(i));
             }
             System.out.println("process " + option + " " + args);
             return args.stream().filter(s -> s.startsWith("arg")).count() == argCount;
diff --git a/langtools/test/jdk/javadoc/tool/T4994049/T4994049.java b/langtools/test/jdk/javadoc/tool/T4994049/T4994049.java
index a5b98dbacb6..aa6329fff57 100644
--- a/langtools/test/jdk/javadoc/tool/T4994049/T4994049.java
+++ b/langtools/test/jdk/javadoc/tool/T4994049/T4994049.java
@@ -41,6 +41,7 @@ import javax.lang.model.SourceVersion;
 import javax.lang.model.element.ElementKind;
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
+import javax.lang.model.util.ElementFilter;
 
 import com.sun.source.tree.CompilationUnitTree;
 import com.sun.source.tree.LineMap;
@@ -59,7 +60,7 @@ public class T4994049 implements Doclet {
         DocTrees trees = root.getDocTrees();
 
         SourcePositions sourcePositions = trees.getSourcePositions();
-        for (TypeElement klass : root.getIncludedTypeElements()) {
+        for (TypeElement klass : ElementFilter.typesIn(root.getIncludedElements())) {
             for (ExecutableElement method : getMethods(klass)) {
                 if (method.getSimpleName().toString().equals("tabbedMethod")) {
                     TreePath path = trees.getPath(method);
diff --git a/langtools/test/jdk/javadoc/tool/completionFailure/CompletionFailure.java b/langtools/test/jdk/javadoc/tool/completionFailure/CompletionFailure.java
index af8c34eb13f..582fc3aedc3 100644
--- a/langtools/test/jdk/javadoc/tool/completionFailure/CompletionFailure.java
+++ b/langtools/test/jdk/javadoc/tool/completionFailure/CompletionFailure.java
@@ -35,6 +35,7 @@ import java.util.*;
 
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.TypeElement;
+import javax.lang.model.util.ElementFilter;
 
 import jdk.javadoc.doclet.Doclet;
 import jdk.javadoc.doclet.DocletEnvironment;
@@ -54,7 +55,7 @@ public class CompletionFailure implements Doclet {
     }
 
     public boolean run(DocletEnvironment root) {
-        Set<TypeElement> classes = root.getIncludedTypeElements();
+        Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
         if (classes.size() != 1)
             throw new Error("1 " + Arrays.asList(classes));
         return true;
diff --git a/langtools/test/jdk/javadoc/tool/dupOk/DupOk.java b/langtools/test/jdk/javadoc/tool/dupOk/DupOk.java
index 4e55b568d18..d2c09cd7737 100644
--- a/langtools/test/jdk/javadoc/tool/dupOk/DupOk.java
+++ b/langtools/test/jdk/javadoc/tool/dupOk/DupOk.java
@@ -36,6 +36,7 @@ import javax.lang.model.SourceVersion;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ElementKind;
 import javax.lang.model.element.TypeElement;
+import javax.lang.model.util.ElementFilter;
 
 import jdk.javadoc.doclet.Doclet;
 import jdk.javadoc.doclet.Reporter;
@@ -62,7 +63,7 @@ public class DupOk implements Doclet
     }
 
     public boolean run(DocletEnvironment root) {
-        Set<TypeElement> classes = root.getIncludedTypeElements();
+        Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
         if (classes.size() != 2)
             throw new Error("1 " + Arrays.asList(classes));
         for (TypeElement clazz : classes) {
diff --git a/langtools/test/jdk/javadoc/tool/example/Example.java b/langtools/test/jdk/javadoc/tool/example/Example.java
new file mode 100644
index 00000000000..a156ebb18e2
--- /dev/null
+++ b/langtools/test/jdk/javadoc/tool/example/Example.java
@@ -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();
+    }
+}
diff --git a/langtools/test/jdk/javadoc/tool/example/Tester.java b/langtools/test/jdk/javadoc/tool/example/Tester.java
new file mode 100644
index 00000000000..597cf281e9c
--- /dev/null
+++ b/langtools/test/jdk/javadoc/tool/example/Tester.java
@@ -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));
+    }
+}
diff --git a/langtools/test/jdk/javadoc/tool/example/overview.html b/langtools/test/jdk/javadoc/tool/example/overview.html
new file mode 100644
index 00000000000..f9f5aaba0bc
--- /dev/null
+++ b/langtools/test/jdk/javadoc/tool/example/overview.html
@@ -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>
diff --git a/langtools/test/jdk/javadoc/tool/modules/ModuleTestBase.java b/langtools/test/jdk/javadoc/tool/modules/ModuleTestBase.java
index a63350522a0..b2fc0ceba9c 100644
--- a/langtools/test/jdk/javadoc/tool/modules/ModuleTestBase.java
+++ b/langtools/test/jdk/javadoc/tool/modules/ModuleTestBase.java
@@ -32,6 +32,7 @@ import java.util.List;
 import java.util.Locale;
 import java.util.Set;
 import java.util.TreeSet;
+import java.util.stream.Collectors;
 
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.Element;
@@ -336,9 +337,7 @@ public class ModuleTestBase extends TestRunner {
         public boolean run(DocletEnvironment docenv) {
             ps.println("ModuleMode" + FS + docenv.getModuleMode());
             printDataSet("Specified", docenv.getSpecifiedElements());
-            printDataSet("Included", docenv.getIncludedModuleElements());
-            printDataSet("Included", docenv.getIncludedPackageElements());
-            printDataSet("Included", docenv.getIncludedTypeElements());
+            printDataSet("Included", docenv.getIncludedElements());
             printDataSet("Selected", getAllSelectedElements(docenv));
             System.out.println(sw);
             return true;
@@ -353,21 +352,24 @@ public class ModuleTestBase extends TestRunner {
                 if (rc != 0) return rc;
                 return Integer.compare(e1.hashCode(), e2.hashCode());
             });
-            for (ModuleElement me : docenv.getIncludedModuleElements()) {
+            Set<? extends Element> elements = docenv.getIncludedElements();
+            for (ModuleElement me : ElementFilter.modulesIn(elements)) {
                 addEnclosedElements(docenv, result, me);
             }
-            for (PackageElement pe : docenv.getIncludedPackageElements()) {
+            for (PackageElement pe : ElementFilter.packagesIn(elements)) {
                 addEnclosedElements(docenv, result, docenv.getElementUtils().getModuleOf(pe));
                 addEnclosedElements(docenv, result, pe);
             }
-            for (TypeElement te : docenv.getIncludedTypeElements()) {
+            for (TypeElement te : ElementFilter.typesIn(elements)) {
                 addEnclosedElements(docenv, result, te);
             }
             return result;
         }
 
         void addEnclosedElements(DocletEnvironment docenv, Set<Element> result, Element e) {
-            List<? extends Element> elems = docenv.getSelectedElements(e.getEnclosedElements());
+            List<Element> elems = e.getEnclosedElements().stream()
+                    .filter(el -> docenv.isIncluded(el))
+                    .collect(Collectors.toList());
             result.addAll(elems);
             for (TypeElement t : ElementFilter.typesIn(elems)) {
                 addEnclosedElements(docenv, result, t);
diff --git a/langtools/test/jdk/javadoc/tool/sourceOnly/p/SourceOnly.java b/langtools/test/jdk/javadoc/tool/sourceOnly/p/SourceOnly.java
index 07d92f7e7a9..7643dddefbb 100644
--- a/langtools/test/jdk/javadoc/tool/sourceOnly/p/SourceOnly.java
+++ b/langtools/test/jdk/javadoc/tool/sourceOnly/p/SourceOnly.java
@@ -29,6 +29,8 @@ import java.util.Locale;
 import java.util.Set;
 
 import javax.lang.model.SourceVersion;
+import javax.lang.model.element.TypeElement;
+import javax.lang.model.util.ElementFilter;
 
 import jdk.javadoc.doclet.Doclet;
 import jdk.javadoc.doclet.DocletEnvironment;
@@ -42,9 +44,10 @@ public class SourceOnly implements Doclet {
 
     @Override
     public boolean run(DocletEnvironment root) {
-        if (root.getIncludedTypeElements().size() != 1)
+        Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
+        if (classes.size() != 1)
             throw new Error("wrong set of classes documented: " +
-                    Arrays.asList(root.getIncludedTypeElements()));
+                    Arrays.asList(classes));
         return true;
     }
 
diff --git a/langtools/test/jdk/javadoc/tool/sourceOption/SourceOption.java b/langtools/test/jdk/javadoc/tool/sourceOption/SourceOption.java
index 6341f591d96..4798aa178b9 100644
--- a/langtools/test/jdk/javadoc/tool/sourceOption/SourceOption.java
+++ b/langtools/test/jdk/javadoc/tool/sourceOption/SourceOption.java
@@ -61,6 +61,7 @@ import java.util.Locale;
 import java.util.Set;
 
 import javax.lang.model.SourceVersion;
+import javax.lang.model.util.ElementFilter;
 import javax.tools.Diagnostic.Kind;
 
 import jdk.javadoc.doclet.Doclet;
@@ -92,7 +93,7 @@ public class SourceOption implements Doclet {
     }
 
     public boolean run(DocletEnvironment root) {
-        root.getIncludedTypeElements();
+        ElementFilter.typesIn(root.getIncludedElements());
         return true;
     }
 
diff --git a/langtools/test/tools/lib/toolbox/JavadocTask.java b/langtools/test/tools/lib/toolbox/JavadocTask.java
index ae31032934f..1975d699d9a 100644
--- a/langtools/test/tools/lib/toolbox/JavadocTask.java
+++ b/langtools/test/tools/lib/toolbox/JavadocTask.java
@@ -179,6 +179,16 @@ public class JavadocTask extends AbstractTask<JavadocTask> {
         return this;
     }
 
+    /**
+     * Sets the options.
+     * @param options the options
+     * @return this task object
+     */
+    public JavadocTask options(List<String> options) {
+        this.options = options;
+        return this;
+    }
+
     /**
      * Sets the files to be documented.
      * @param files the files