Summary

Tie together uses of the term 'standard doclet'

Problem

There are 3 spec documents that define or use the term "standard doclet", but these are not coordinated in any meaningful way.

Solution

Cross-link the following pages which define or use the term "standard doclet".

• The Doc Comment Spec for the Standard Doclet
• The javadoc man page
• The API spec for the StandardDoclet class

Specification

The changes to the doc comment for the StandardDoclet class.

(This file is the obvious choice to the defining instance of the term, but we link to the javadoc man page to give it a context when this class may be used.)

--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java
@@ -36,7 +36,10 @@

 /**
  * This doclet generates HTML-formatted documentation for the specified modules,
- * packages and types.
+ * packages and types. It is the doclet that is used by the
+ * <a href="{@docRoot}/../specs/man/javadoc.html"><em>javadoc</em></a> tool
+ * and the {@linkplain javax.tools.ToolProvider#getSystemDocumentationTool
+ * system documentation tool} when no other doclet is specified to be used.
  *
  * <h2><a id="user-defined-taglets">User-Defined Taglets</a></h2>
  *

The changes to the Doc Comment Spec.

(This file uses the term "standard doclet" so we just link to the defining instance, to give it context.)

@@ -7,7 +7,7 @@ lang: en
 ---

 This document specifies the form of documentation comments recognized
-by the standard doclet for the `javadoc` tool in JDK @@VERSION_SPECIFICATION@@,
+by the [standard doclet] for the [`javadoc`][tool] tool in JDK @@VERSION_SPECIFICATION@@,
 used to generate HTML documentation for an API.

 In the context of the `javadoc` tool, the interpretation of the
@@ -17,6 +17,9 @@ as the standard doclet, or they may support an alternate syntax.
 However, due to support in many tools, the syntax supported by the
 standard doclet has become a *de facto* standard.

+[standard doclet]: ../../api/jdk.javadoc/jdk/javadoc/doclet/StandardDoclet.html
+[tool]: ../man/javadoc.html
+
 ## General Syntax

 Documentation comments are stylized comments appearing in source code, near to

Changes to the javadoc man page:

(This page extensively references the term "standard doclet" so we link the initial instance, and give a bit more of an introductory paragraph about the tool.) @@ -45,11 +45,19 @@ javadoc - generate HTML pages of API documentation from Java source files ## Description

 The `javadoc` tool parses the declarations and documentation comments in a set
-of Java source files and produces corresponding HTML pages that describe (by
-default) the public and protected classes, nested and implicitly declared
-classes (but not anonymous inner classes), interfaces, constructors, methods,
-and fields. You can use the `javadoc` tool to generate the API documentation or
-the implementation documentation for a set of source files.
+of Java source files and processes them using a pluggable back-end called a
+[_doclet_][doclet].
+
+The [_standard doclet_][standard-doclet] is the one that is used by default,
+and can produce corresponding HTML pages that describe the public and protected
+classes, nested and implicitly declared classes(but not anonymous inner classes),
+interfaces, constructors, methods, and fields. The standard doclet interprets
+the content of documentation comments according to the
+[JavaDoc Documentation Comment Specification for the Standard Doclet][doc-comment-spec].
+Custom tags in documentation comments are supported by means of [taglets][taglet].
+
+You can use the `javadoc` tool and the standard doclet to generate the API
+documentation or the implementation documentation for a set of source files.

 You can run the `javadoc` tool on entire packages, individual source files, or
 both. When documenting entire packages, you can use the `-subpackages` option
@@ -57,6 +65,11 @@ either to recursively traverse a directory and its subdirectories, or to pass
 in an explicit list of package names. When you document individual source
 files, pass in a list of Java source file names.

+[doc-comment-spec]: ../javadoc/doc-comment-spec.html
+[doclet]: ../../api/jdk.javadoc/jdk/javadoc/doclet/Doclet.html
+[standard-doclet]: ../../api/jdk.javadoc/jdk/javadoc/doclet/StandardDoclet.html
+[taglet]: ../../api/jdk.javadoc/jdk/javadoc/doclet/Taglet.html
+
 ### Conformance

 The standard doclet does not validate the content of documentation comments for