diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
index 39a5f174ffb..981b73bb3ad 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Doclet.java
@@ -58,6 +58,16 @@ import javax.lang.model.SourceVersion;
  *
  * @since 9
  */
+//
+// TODO: (spec) Better define the call order.
+//       Define which methods are called when, by the container.
+//       E.g. at any time, or after or before some other method(s), etc.
+//
+// TODO: (spec) Specify that the container calls Doclet's and Option's methods
+//       in a thread-safe manner. That is, maybe by different threads, but never
+//       concurrently, and using all the necessary synchronization. So, the
+//       implementors of Doclets don't have to be concerned with any of that.
+//
 public interface Doclet {
 
     /**
@@ -67,6 +77,9 @@ public interface Doclet {
      * @param locale the locale to be used
      * @param reporter the reporter to be used
      */
+    //
+    // TODO: (spec, wordsmithing?) What are these "doclet components"?
+    //
     void init(Locale locale, Reporter reporter);
 
     /**
@@ -76,6 +89,9 @@ public interface Doclet {
      *
      * @return name of the Doclet
      */
+    //
+    // TODO: (spec) How is this used? (E.g. maybe to identify Doclet to the user?
+    //
     String getName();
 
     /**
@@ -83,6 +99,11 @@ public interface Doclet {
      *
      * @return a set containing all the supported options, an empty set if none
      */
+    //
+    // TODO: (spec) How is this method used?
+    // Should we say that this set *comprises* all the supported options?
+    // i.e. it contains all the options and nothing else.
+    //
     Set<? extends Option> getSupportedOptions();
 
     /**
@@ -92,6 +113,12 @@ public interface Doclet {
      * @return  the language version supported by this doclet, usually
      * the latest version
      */
+    //
+    // TODO: (spec) What happens if the returned SourceVersion does not
+    //       agree with the container? What is the semantics of this value?
+    //
+    // TODO: (impl) I couldn't find where it is called
+    //
     SourceVersion getSupportedSourceVersion();
 
     /**
@@ -101,17 +128,30 @@ public interface Doclet {
      * @param environment from which essential information can be extracted
      * @return true on success
      */
+    //
+    // TODO: (spec) What does success mean here? How should Doclet decide
+    //       what to return? What are the implications of returning false?
+    //       Should a doclet in this case say something to "reporter"?
+    //
     boolean run(DocletEnvironment environment);
 
     /**
      * An encapsulation of option name, aliases, parameters and descriptions
      * as used by the Doclet.
      */
+    // TODO: should we talk separately about typical options and then the
+    //       options ending with ':' (e.g. "-Xdoclint:")?
+    //       The latter are processed somewhat differently. For example, they
+    //       bypass getArgumentCount
+    //
     interface Option {
         /**
          * Returns the number of arguments, this option will consume.
          * @return number of consumed arguments
          */
+        //
+        // TODO: (spec) How is this method used?
+        //
         int getArgumentCount();
 
         /**
@@ -119,12 +159,21 @@ public interface Doclet {
          * return the synopsis of the option such as, "groups the documents".
          * @return description if set, otherwise an empty String
          */
+        //
+        // TODO: (spec) How is this method used?
+        //
+        // TODO: (spec) Should it mention that this should better be localized
+        //       as it probably displayed to the user?
+        //
         String getDescription();
 
         /**
          * Returns the option kind.
          * @return the kind of this option
          */
+        //
+        // TODO: (spec) How is this method used?
+        //
         Option.Kind getKind();
 
         /**
@@ -133,12 +182,21 @@ public interface Doclet {
          * option "-classpath", with an alias "--class-path".
          * @return the names of the option
          */
+        //
+        // TODO: (spec) The returned list must have at least one name.
+        //       Probably link to some good naming conventions
+        //       (e.g. GNU, https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html#Command_002dLine-Interfaces).
+        //
         List<String> getNames();
 
         /**
          * Returns the parameters of the option. For instance "name &lt;p1&gt;:&lt;p2&gt;.."
          * @return parameters if set, otherwise an empty String
          */
+        //
+        // TODO: (spec) How is this method used?
+        //       Is there a link between this method and getArgumentCount?
+        //
         String getParameters();
 
         /**
@@ -148,6 +206,18 @@ public interface Doclet {
          * @param arguments a list encapsulating the arguments
          * @return true if operation succeeded, false otherwise
          */
+        //
+        // TODO: (spec) what is the "option" parameter? Is it one of the names
+        //       from `getNames()`?
+        //
+        // TODO: (spec) What are the effects of the returned value?
+        //
+        // TODO: (spec) Can this method be called on the same option more than
+        //       once? If so, then Doclet is in charge of keeping all the
+        //       necessary state accumulated between the calls.
+        //
+        // TODO: (spec) Specify exactly how this <option> is selected
+        //
         boolean process(String option, List<String> arguments);
 
         /**
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
index 7ae401e66bf..ff586ebc8e9 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
@@ -45,6 +45,18 @@ import com.sun.source.util.DocTrees;
  *
  * @since 9
  */
+//
+// TODO: (spec) It doesn't capture the essence of what this entity is.
+//       For instance, it could say something to the effect that:
+//       An instance of this type is provided by the container to the doclet.
+//       This instance contains facilities that allow doclet to inspect the
+//       source code.
+//
+// TODO: (spec) Say something about the thread-safety. The point is that a
+//       Doclet might employ multi-threading internally.
+//       If you think that sounds overly pedantic or artificial, see JDK-8214772
+//       and JDK-8214775
+//
 public interface DocletEnvironment {
 
     /**
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java
index eb1b9453562..49890770126 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java
@@ -35,6 +35,25 @@ import com.sun.source.util.DocTreePath;
  *
  * @since 9
  */
+//
+// TODO: (spec) It doesn't capture the essence of what this entity is.
+//       For instance, it could say something to the effect that:
+//       An instance of this type is provided by the container to the doclet.
+//       This instance is expected to be used by the doclet for communicating
+//       its activities and its status to the doclet container.
+//       Once again, why can't the doclet do this by returning a result or
+//       throwing an exception? Okay. This is definitely more flexible, async
+//       style.
+//
+// TODO: (spec) How is reporting an error affects the run?
+//       Will the doclet consider reporting an error as a failure?
+//
+// TODO: (spec) Say something about the thread-safety. The point is that a
+//       Doclet might employ multi-threading internally.
+//       Should the doclet synchronize calls to methods of this interface?
+//       If you think that sounds overly pedantic or artificial, see JDK-8214772
+//       and JDK-8214775
+//
 public interface Reporter {
 
     /**
@@ -43,6 +62,9 @@ public interface Reporter {
      * @param kind specify the diagnostic kind
      * @param msg message to print
      */
+    //
+    // TODO: (spec) what is "error count"?
+    //
     void print(Diagnostic.Kind kind, String msg);
 
     /**
@@ -52,6 +74,9 @@ public interface Reporter {
      * @param path the DocTreePath of item where the error occurs
      * @param msg message to print
      */
+    //
+    // TODO: (spec) what is "error count"?
+    //
     void print(Diagnostic.Kind kind, DocTreePath path, String msg);
 
     /**
@@ -61,5 +86,8 @@ public interface Reporter {
      * @param e the Element for which  the error occurs
      * @param msg message to print
      */
+    //
+    // TODO: (spec) what is "error count"?
+    //
     void print(Diagnostic.Kind kind, Element e, String msg);
 }
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java
index 756227aafc1..2ae09b77dfc 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java
@@ -66,6 +66,9 @@ import jdk.javadoc.internal.doclets.formats.html.HtmlDoclet;
  * @see <a href="{@docRoot}/../specs/javadoc/doc-comment-spec.html">
  *      Documentation Comment Specification for the Standard Doclet</a>
  */
+//
+// TODO: (general) What is the purpose of exposing this class? Extension?
+//
 public class StandardDoclet implements Doclet {
 
     private final HtmlDoclet htmlDoclet;
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java
index 4a1bbd2f79a..5038a2b026f 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java
@@ -76,8 +76,31 @@ import com.sun.source.doctree.DocTree;
  * @since 9
  */
 
+//
+// TODO: there's no requirement that it should be the default constructor.
+//       The phrase would be better as: must have a public no-args constructor
+//       or must have a public constructor with no parameters.
+//
+
+//
+// TODO: (general) It's as if Taglet and StandardDoclet deserve
+//       a separate package
+//
 public interface Taglet {
 
+    //
+    // TODO: define a glossary establishing a relationship between entities such as
+    //       "tag" and "taglet". Explain that there's a tag, an instance of that
+    //       tag, and a taglet which defines the behaviour of all instances of a
+    //       particular tag.
+    //
+    //  Documentation for both
+    //  jdk.javadoc.internal.doclets.toolkit.taglets.Taglet and
+    //  jdk.javadoc.doclet.Taglet occasionally uses plural "tags" instead of a
+    //  singular "tag". This might confuse a reader and they might think that a
+    //  taglet supports multiple differently named tags.
+    //
+
     /**
      * Returns the set of supported locations for block tags.
      * @return the set of supported locations for block tags
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java
index 2e895024b93..39706d563e0 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java
@@ -353,5 +353,13 @@
  * @see jdk.javadoc.doclet.DocletEnvironment
  * @since 9
 */
-
+//
+// TODO: (spec) Provide a better overall picture of this SPI (arguably, it's not an API).
+//       In particular, define what the main pieces are and how these pieces
+//       interact with each other. Some of the pieces that come to mind are:
+//           * The "doclet"
+//           * The "container" that instantiates, interrogates, provides facilities,
+//                 and finally starts the doclet
+//           * Container-provided facilities (the "reporter" and "environment")
+//
 package jdk.javadoc.doclet;