8298405: Implement JEP 467: Markdown Documentation Comments

8329296: Update Elements for '///' documentation comments Co-authored-by: Jim Laskey <jlaskey@openjdk.org> Reviewed-by: prappo, darcy, hannesw
openjdk · May 17, 2024 · 0a58cff · 0a58cff · openjdk-notifier · May 17, 2024
1 parent 39a55e9
commit 0a58cff
Show file tree

Hide file tree

Showing 250 changed files with 26,315 additions and 707 deletions.
diff --git a/make/CompileDemos.gmk b/make/CompileDemos.gmk
@@ -183,7 +183,7 @@ $(eval $(call SetupBuildDemo, SwingSet2, \
 ))
 
 $(eval $(call SetupBuildDemo, Font2DTest, \
-    DISABLED_WARNINGS := rawtypes deprecation unchecked serial cast this-escape, \
+    DISABLED_WARNINGS := rawtypes deprecation unchecked serial cast this-escape dangling-doc-comments, \
     DEMO_SUBDIR := jfc, \
 ))
 

diff --git a/make/autoconf/spec.gmk.template b/make/autoconf/spec.gmk.template
@@ -675,7 +675,7 @@ DOCS_REFERENCE_JAVADOC := @DOCS_REFERENCE_JAVADOC@
 SOURCE_REVISION_TRACKER := $(SUPPORT_OUTPUTDIR)/src-rev/source-revision-tracker
 
 # Interim langtools modules and arguments
-INTERIM_LANGTOOLS_BASE_MODULES := java.compiler jdk.compiler jdk.javadoc
+INTERIM_LANGTOOLS_BASE_MODULES := java.compiler jdk.compiler jdk.internal.md jdk.javadoc
 INTERIM_LANGTOOLS_MODULES := $(addsuffix .interim, $(INTERIM_LANGTOOLS_BASE_MODULES))
 INTERIM_LANGTOOLS_ADD_EXPORTS := \
     --add-exports java.base/sun.reflect.annotation=jdk.compiler.interim \

diff --git a/make/jdk/src/classes/build/tools/taglet/JSpec.java b/make/jdk/src/classes/build/tools/taglet/JSpec.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, 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
@@ -30,6 +30,8 @@
 import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
 import javax.lang.model.element.Element;
 
 import com.sun.source.doctree.DocTree;
@@ -157,7 +159,10 @@ public String toString(List<? extends DocTree> tags, Element elem) {
                     continue;
             }
 
-            String tagText = contents.toString().trim();
+            String tagText = contents.stream()
+                    .map(Object::toString)
+                    .collect(Collectors.joining())
+                    .trim();
             Matcher m = TAG_PATTERN.matcher(tagText);
             if (m.find()) {
                 String chapter = m.group("chapter");

diff --git a/make/jdk/src/classes/build/tools/taglet/ToolGuide.java b/make/jdk/src/classes/build/tools/taglet/ToolGuide.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, 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
@@ -30,6 +30,8 @@
 import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
 import javax.lang.model.element.Element;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
@@ -105,8 +107,11 @@ public String toString(List<? extends DocTree> tags, Element elem) {
                 continue;
             }
 
-            UnknownBlockTagTree blockTag = (UnknownBlockTagTree)tag;
-            String tagText = blockTag.getContent().toString().trim();
+            UnknownBlockTagTree blockTag = (UnknownBlockTagTree) tag;
+            String tagText = blockTag.getContent().stream()
+                    .map(Object::toString)
+                    .collect(Collectors.joining())
+                    .trim();
             Matcher m = TAG_PATTERN.matcher(tagText);
             if (m.matches()) {
                 String name = m.group("name");

diff --git a/make/modules/java.base/Java.gmk b/make/modules/java.base/Java.gmk
@@ -27,7 +27,7 @@
 # new warning is added to javac, it can be temporarily added to the
 # disabled warnings list.
 #
-# DISABLED_WARNINGS_java +=
+DISABLED_WARNINGS_java += dangling-doc-comments
 
 DOCLINT += -Xdoclint:all/protected \
     '-Xdoclint/package:java.*,javax.*'

diff --git a/make/modules/jdk.incubator.vector/Java.gmk b/make/modules/jdk.incubator.vector/Java.gmk
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2020, 2024, 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
@@ -23,4 +23,6 @@
 # questions.
 #
 
+DISABLED_WARNINGS_java += dangling-doc-comments
+
 DOCLINT += -Xdoclint:all/protected
diff --git a/make/modules/jdk.jpackage/Java.gmk b/make/modules/jdk.jpackage/Java.gmk
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2020, 2024, 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
@@ -23,6 +23,8 @@
 # questions.
 #
 
+DISABLED_WARNINGS_java += dangling-doc-comments
+
 COPY += .gif .png .txt .spec .script .prerm .preinst \
     .postrm .postinst .list .sh .desktop .copyright .control .plist .template \
     .icns .scpt .wxs .wxl .wxi .ico .bmp .tiff .service

diff --git a/make/modules/jdk.unsupported/Java.gmk b/make/modules/jdk.unsupported/Java.gmk
@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2024, 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.  Oracle designates this
+# particular file as subject to the "Classpath" exception as provided
+# by Oracle in the LICENSE file that accompanied this code.
+#
+# 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.
+#
+
+DISABLED_WARNINGS_java += dangling-doc-comments
diff --git a/make/test/BuildMicrobenchmark.gmk b/make/test/BuildMicrobenchmark.gmk
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2018, 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2018, 2024, 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
@@ -95,7 +95,7 @@ $(eval $(call SetupJavaCompilation, BUILD_JDK_MICROBENCHMARK, \
     SMALL_JAVA := false, \
     CLASSPATH := $(JMH_COMPILE_JARS), \
     DISABLED_WARNINGS := restricted this-escape processing rawtypes cast \
-        serial preview, \
+        serial preview dangling-doc-comments, \
     SRC := $(MICROBENCHMARK_SRC), \
     BIN := $(MICROBENCHMARK_CLASSES), \
     JAVAC_FLAGS := \

diff --git a/src/java.base/share/classes/jdk/internal/jrtfs/JrtFileAttributes.java b/src/java.base/share/classes/jdk/internal/jrtfs/JrtFileAttributes.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2024, 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
@@ -46,7 +46,7 @@ final class JrtFileAttributes  implements BasicFileAttributes {
         this.node = node;
     }
 
-    ///////// basic attributes ///////////
+    //-------- basic attributes --------
     @Override
     public FileTime creationTime() {
         return node.creationTime();
@@ -92,7 +92,7 @@ public Object fileKey() {
         return node.resolveLink(true);
     }
 
-    ///////// jrtfs specific attributes ///////////
+    //-------- jrtfs specific attributes --------
     /**
      * Compressed resource file. If not available or not applicable, 0L is
      * returned.

diff --git a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
@@ -277,51 +277,124 @@ default Set<? extends ModuleElement> getAllModuleElements() {
             getElementValuesWithDefaults(AnnotationMirror a);
 
     /**
-     * Returns the text of the documentation (&quot;Javadoc&quot;)
+     * Returns the text of the documentation (&quot;JavaDoc&quot;)
      * comment of an element.
      *
-     * <p> A documentation comment of an element is a comment that
-     * begins with "{@code /**}", ends with a separate
-     * "<code>*&#47;</code>", and immediately precedes the element,
-     * ignoring white space, annotations, end-of-line-comments ({@code
-     * "//"} comments), and intermediate traditional comments
-     * (<code>"/* ... *&#47;"</code> comments) that are not doc comments.
-     * Therefore, a documentation comment
-     * contains at least three "{@code *}" characters.  The text
+     * <p>A documentation comment of an element is a particular kind
+     * of comment that immediately precedes the element, ignoring
+     * white space, annotations and any other comments that are
+     * not themselves documentation comments.
+     *
+     * <p>There are two kinds of documentation comments, either based on
+     * <em>traditional comments</em> or based on a series of
+     * <em>end-of-line comments</em>. For both kinds, the text
      * returned for the documentation comment is a processed form of
-     * the comment as it appears in source code:
+     * the comment as it appears in source code, as described below.
+     *
+     * <p>A {@linkplain DocCommentKind#TRADITIONAL traditional
+     * documentation comment} is a traditional comment that begins
+     * with "{@code /**}", and ends with a separate "<code>*&#47;</code>".
+     * (Therefore, such a comment contains at least three "{@code *}"
+     * characters.)
+     * The lines of such a comment are processed as follows:
      * <ul>
      * <li>The leading "{@code /**}" is removed, as are any
      * immediately following space characters on that line. If all the
      * characters of the line are removed, it makes no contribution to
      * the returned comment.
      * <li>For subsequent lines
      * of the doc comment starting after the initial "{@code /**}",
-     * if the lines start with <em>zero</em> or more whitespace characters followed by
-     * <em>one</em> or more "{@code *}" characters,
+     * if the lines start with <em>zero</em> or more whitespace characters
+     * followed by <em>one</em> or more "{@code *}" characters,
      * those leading whitespace characters are discarded as are any
      * consecutive "{@code *}" characters appearing after the white
      * space or starting the line.
      * Otherwise, if a line does not have a prefix of the described
      * form, the entire line is retained.
      * <li> The trailing "<code>*&#47;</code>" is removed. The line
      * with the trailing" <code>*&#47;</code>" also undergoes leading
-     * space and "{@code *}" character removal as described above. If all the characters
-     * of the line are removed, it makes no contribution to the
-     * returned comment.
+     * space and "{@code *}" character removal as described above.
+     * <li>The processed lines are then concatenated together,
+     * separated by newline ("{@code \n}") characters, and returned.
+     * </ul>
+     *
+     * <p>An {@linkplain DocCommentKind#END_OF_LINE end-of-line
+     * documentation comment} is a series of adjacent end-of-line
+     * comments, each on a line by itself, ignoring any whitespace
+     * characters at the beginning of the line, and each beginning
+     * with "{@code ///}".
+     * The lines of such a comment are processed as follows:
+     * <ul>
+     * <li>Any leading whitespace and the three initial "{@code /}"
+     * characters are removed from each line.
+     * <li>The lines are shifted left, by removing leading whitespace
+     * characters, until the non-blank line with the least leading
+     * whitespace characters has no remaining leading whitespace
+     * characters.
+     * <li>Additional leading whitespace characters and any trailing
+     * whitespace characters in each line are preserved.
+     * <li>
+     * The processed lines are then concatenated together,
+     * separated by newline ("{@code \n}") characters, and returned.
+     * If the last line is not blank, the returned value will not be
+     * terminated by a newline character.
      * </ul>
-     * The processed lines are then
-     * concatenated together (including line terminators) and
-     * returned.
      *
      * @param e  the element being examined
      * @return the documentation comment of the element, or {@code null}
      *          if there is none
      * @jls 3.6 White Space
      * @jls 3.7 Comments
+     *
+     * @apiNote
+     * Documentation comments are processed by the standard doclet
+     * used by the {@code javadoc} tool to generate API documentation.
      */
     String getDocComment(Element e);
 
+    /**
+     * {@return the kind of the documentation comment for the given element,
+     * or {@code null} if there is no comment or the kind is not known}
+     *
+     * @implSpec The default implementation of this method returns
+     * {@code null}.
+     *
+     * @param e the element being examined
+     * @since 23
+     */
+    default DocCommentKind getDocCommentKind(Element e) {
+        return null;
+    }
+
+    /**
+     * The kind of documentation comment.
+     *
+     * @since 23
+     */
+    enum DocCommentKind {
+        /**
+         * The kind of comments whose lines are prefixed by {@code ///}.
+         *
+         * @apiNote
+         * The standard doclet used by the {@code javadoc} tool treats these comments
+         * as containing Markdown and documentation comment tags.
+         *
+         *
+         * @see <a href="https://openjdk.org/jeps/467">
+         * JEP 467: Markdown Documentation Comments</a>
+         */
+        END_OF_LINE,
+
+        /**
+         * The kind of comments that begin with {@code /**}.
+         *
+         * @apiNote
+         * The standard doclet used by the {@code javadoc} tool treats these comments
+         * as containing HTML and documentation comment tags.
+         */
+        TRADITIONAL
+    }
+
     /**
      * {@return {@code true} if the element is deprecated, {@code false} otherwise}
      *

diff --git a/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java b/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024, 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
@@ -161,6 +161,14 @@ enum Kind {
          */
         LITERAL("literal"),
 
+        /**
+         * Used for instances of {@link RawTextTree}
+         * representing a fragment of Markdown content.
+         *
+         * @since 23
+         */
+        MARKDOWN,
+
         /**
          * Used for instances of {@link ParamTree}
          * representing an {@code @param} tag.

diff --git a/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java b/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024, 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
@@ -247,6 +247,22 @@ default R visitProvides(ProvidesTree node, P p) {
         return visitOther(node, p);
     }
 
+    /**
+     * Visits a {@code RawTextTree} node.
+     *
+     * @implSpec Visits the provided {@code RawTextTree} node
+     * by calling {@code visitOther(node, p)}.
+     *
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     *
+     * @since 23
+     */
+    default R visitRawText(RawTextTree node, P p) {
+        return visitOther(node, p);
+    }
+
     /**
      * Visits a {@code ReferenceTree} node.
      * @param node the node being visited

diff --git a/src/jdk.compiler/share/classes/com/sun/source/doctree/InheritDocTree.java b/src/jdk.compiler/share/classes/com/sun/source/doctree/InheritDocTree.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024, 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
@@ -33,6 +33,11 @@
  *    {&#064;inheritDoc supertype}
  * </pre>
  *
+ * @apiNote
+ * There is no requirement that the comment containing the tag and the comment
+ * containing the inherited documentation should either be both Markdown comments
+ * or both traditional (not Markdown) comments.
+ *
  * @since 1.8
  */
 public interface InheritDocTree extends InlineTagTree {