make/autoconf/spec.gmk.template

@@ -694,7 +694,7 @@ BUILD_JAR = @FIXPATH@ $(BUILD_JDK)/bin/jar
 DOCS_REFERENCE_JAVADOC := @DOCS_REFERENCE_JAVADOC@
 
 # 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 \

make/jdk/src/classes/build/tools/taglet/JSpec.java

@@ -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");

make/jdk/src/classes/build/tools/taglet/ToolGuide.java

@@ -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");

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java

@@ -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.

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java

@@ -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

src/jdk.compiler/share/classes/com/sun/source/doctree/InheritDocTree.java

@@ -33,6 +33,11 @@
  *    {@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 {

src/jdk.compiler/share/classes/com/sun/source/doctree/RawTextTree.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2022, 2023, 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.
+ */
+
+package com.sun.source.doctree;
+
+/**
+ * A tree node for a fragment of uninterpreted raw text content.
+ *
+ * <p>
+ * The content may contain any text except that for
+ * {@linkplain InlineTagTree inline tags}.
+ *
+ * <p>The format of the content is indicated by the {@linkplain #getKind() kind}
+ * of the tree node.
+ *
+ * @apiNote
+ * This class may be used to represent tree nodes containing
+ * {@linkplain DocTree.Kind#MARKDOWN Markdown} text.
+ * Such nodes will typically exist in a list of {@code DocTree} nodes,
+ * along with other kinds of {@code DocTree} nodes, such as for inline tags.
+ * When processing any such list, any non-Markdown nodes will be processed
+ * recursively first, and then treated as opaque objects within the remaining
+ * stream of Markdown nodes. Thus, the content of any non-Markdown nodes will
+ * not affect how the Markdown nodes will be processed.
+ *
+ * @since 23
+ */
+public interface RawTextTree extends DocTree {
+    /**
+     * {@return the content}
+     */
+    String getContent();
+}

src/jdk.compiler/share/classes/com/sun/source/doctree/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2023, 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
@@ -28,7 +28,6 @@
  * trees (AST).
  *
  * @spec javadoc/doc-comment-spec.html Documentation Comment Specification for the Standard Doclet
- * @author Jonathan Gibbons
  * @since 1.8
  *
  */

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java

@@ -52,6 +52,7 @@
 import com.sun.source.doctree.InheritDocTree;
 import com.sun.source.doctree.LinkTree;
 import com.sun.source.doctree.LiteralTree;
+import com.sun.source.doctree.RawTextTree;
 import com.sun.source.doctree.ParamTree;
 import com.sun.source.doctree.ProvidesTree;
 import com.sun.source.doctree.ReferenceTree;
@@ -289,6 +290,18 @@ default InheritDocTree newInheritDocTree(ReferenceTree supertype) {
      */
     ProvidesTree newProvidesTree(ReferenceTree name, List<? extends DocTree> description);
 
+    /**
+     * Creates a new {@code RawTextTree} object, to represent a fragment of uninterpreted raw text.
+     *
+     * @param kind the kind of text
+     * @param code the code
+     * @return a {@code RawTextTree} object
+     * @throws IllegalArgumentException if the kind is not a recognized kind for raw text
+     *
+     * @since 23
+     */
+    RawTextTree newRawTextTree(DocTree.Kind kind, String code);
+
     /**
      * Creates a new {@code ReferenceTree} object, to represent a reference to an API element.
      *

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java

@@ -413,6 +413,22 @@ public R visitProvides(ProvidesTree node, P p) {
         return r;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @implSpec This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     *
+     * @since 23
+     */
+    @Override
+    public R visitRawText(RawTextTree node, P p) {
+        return null;
+    }
+
     /**
      * {@inheritDoc}
      *

src/jdk.compiler/share/classes/com/sun/source/util/DocTrees.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2023, 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
@@ -28,6 +28,7 @@
 import java.io.IOException;
 import java.text.BreakIterator;
 import java.util.List;
+
 import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.PackageElement;
@@ -36,9 +37,12 @@
 import javax.tools.FileObject;
 import javax.tools.JavaCompiler.CompilationTask;
 
+import com.sun.source.doctree.BlockTagTree;
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.doctree.DocTree;
 import com.sun.source.doctree.EntityTree;
+import com.sun.source.doctree.InlineTagTree;
+import com.sun.source.doctree.LinkTree;
 import com.sun.source.tree.CompilationUnitTree;
 
 /**
@@ -84,6 +88,28 @@ public static DocTrees instance(ProcessingEnvironment env) {
      */
     public abstract BreakIterator getBreakIterator();
 
+    /**
+     * The style of a documentation comment.
+     *
+     * @since 23
+     */
+    public enum CommentKind {
+        /** The style of comments whose lines are prefixed by {@code ///}. */
+        LINE,
+        /** The style of comments that begin with {@code /**}. */
+        BLOCK
+    }
+
+    /**
+     * {@return the style of the documentation comment associated with a tree node}
+     *
+     * @param path the path for the tree node
+     *
+     * @see Trees#getPath(Element)
+     * @since 23
+     */
+    public abstract CommentKind getDocCommentKind(TreePath path);
+
     /**
      * Returns the doc comment tree, if any, for the Tree node identified by a given TreePath.
      * Returns {@code null} if no doc comment was found.
@@ -113,27 +139,37 @@ public static DocTrees instance(ProcessingEnvironment env) {
     public abstract DocCommentTree getDocCommentTree(Element e);
 
     /**
-     * Returns the doc comment tree of the given file. The file must be
-     * an HTML file, in which case the doc comment tree represents the
-     * entire contents of the file.
-     * Returns {@code null} if no doc comment was found.
+     * Returns the doc comment tree of the given file, which must
+     * be of one of the supported file types.
+     *
+     * <p>The supported file types are:
+     * <ul>
+     * <li>HTML files, identified by a file name ending in {@code .html},
+     * <li>Markdown files, identified by a file name ending in {@code .md}.
+     * </ul>
      * Future releases may support additional file types.
      *
      * @implNote The default implementation of this method returns a
      * new {@code DocCommentTree} instance for each invocation.
      *
      * @param fileObject the content container
      * @return the doc comment tree
+     * @throws IllegalArgumentException if the file type is not supported
+     *
      * @since 9
      */
     public abstract DocCommentTree getDocCommentTree(FileObject fileObject);
 
     /**
-     * Returns the doc comment tree of the given file whose path is
-     * specified relative to the given element. The file must be an HTML
-     * file, in which case the doc comment tree represents the contents
-     * of the &lt;body&gt; tag, and any enclosing tags are ignored.
-     * Returns {@code null} if no doc comment was found.
+     * Returns the doc comment tree of the given file, which must
+     * be of one of the supported file types, and whose path is
+     * specified relative to the given element.
+     *
+     * <p>The supported file types are:
+     * <ul>
+     * <li>HTML files, identified by a file name ending in {@code .html},
+     * <li>Markdown files, identified by a file name ending in {@code .md}.
+     * </ul>
      * Future releases may support additional file types.
      *
      * @implNote The default implementation of this method returns a
@@ -142,16 +178,20 @@ public static DocTrees instance(ProcessingEnvironment env) {
      * @param e an element whose path is used as a reference
      * @param relativePath the relative path from the Element
      * @return the doc comment tree
-     * @throws java.io.IOException if an exception occurs
+     * @throws IOException if an exception occurs
+     * @throws IllegalArgumentException if the file type is not supported
      *
      * @since 9
      */
     public abstract DocCommentTree getDocCommentTree(Element e, String relativePath) throws IOException;
 
     /**
-     * Returns a doc tree path containing the doc comment tree of the given file.
-     * The file must be an HTML file, in which case the doc comment tree represents
-     * the contents of the {@code <body>} tag, and any enclosing tags are ignored.
+     * Returns a doc tree path containing the doc comment tree of the given file,
+     * which must be of one of the supported file types.
+     *
+     * Supported file types are HTML files and Markdown files.
+     * Future releases may support additional file types.
+     *
      * Any references to source code elements contained in {@code @see} and
      * {@code {@link}} tags in the doc comment tree will be evaluated in the
      * context of the given package element.
@@ -161,7 +201,7 @@ public static DocTrees instance(ProcessingEnvironment env) {
      * @param packageElement a package element to associate with the given file object
      * representing a legacy package.html, null otherwise
      * @return a doc tree path containing the doc comment parsed from the given file
-     * @throws IllegalArgumentException if the fileObject is not an HTML file
+     * @throws IllegalArgumentException if the file type is not supported
      *
      * @since 9
      */

src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java

@@ -366,6 +366,22 @@ public R visitProvides(ProvidesTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @implSpec This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     *
+     * @since 23
+     */
+    @Override
+    public R visitRawText(RawTextTree node, P p) {
+        return defaultAction(node, p);
+    }
+
     /**
      * {@inheritDoc}
      *