8325168: JShell should support Markdown comments

src/jdk.compiler/share/classes/module-info.java

@@ -268,8 +268,6 @@
         jdk.javadoc,
         jdk.jshell,
         jdk.internal.md;
-    exports jdk.internal.shellsupport.doc to
-        jdk.jshell;
 
     uses javax.annotation.processing.Processor;
     uses com.sun.source.util.Plugin;

src/jdk.jshell/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -71,6 +71,7 @@
     requires jdk.compiler;
     requires jdk.internal.ed;
     requires jdk.internal.le;
+    requires jdk.internal.md;
     requires jdk.internal.opt;
 
     requires transitive java.compiler;

test/langtools/jdk/internal/shellsupport/doc/FullJavadocHelperTest.java

@@ -28,7 +28,7 @@
  * @library /tools/lib
  * @modules jdk.compiler/com.sun.tools.javac.api
  *          jdk.compiler/com.sun.tools.javac.main
- *          jdk.compiler/jdk.internal.shellsupport.doc
+ *          jdk.jshell/jdk.internal.shellsupport.doc
  * @build toolbox.ToolBox toolbox.JarTask toolbox.JavacTask
  * @run testng/timeout=900/othervm -Xmx1024m FullJavadocHelperTest
  */

test/langtools/jdk/internal/shellsupport/doc/JavadocFormatterTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -26,7 +26,7 @@
  * @bug 8131019 8169561 8261450
  * @summary Test JavadocFormatter
  * @library /tools/lib
- * @modules jdk.compiler/jdk.internal.shellsupport.doc
+ * @modules jdk.jshell/jdk.internal.shellsupport.doc
  * @run testng JavadocFormatterTest
  */
 

test/langtools/jdk/internal/shellsupport/doc/JavadocHelperTest.java

@@ -28,7 +28,7 @@
  * @library /tools/lib
  * @modules jdk.compiler/com.sun.tools.javac.api
  *          jdk.compiler/com.sun.tools.javac.main
- *          jdk.compiler/jdk.internal.shellsupport.doc
+ *          jdk.jshell/jdk.internal.shellsupport.doc
  * @build toolbox.ToolBox toolbox.JarTask toolbox.JavacTask
  * @run testng JavadocHelperTest
  * @key randomness
@@ -93,12 +93,6 @@ public void testJavadoc() throws Exception {
                       " @return value\n");
     }
 
-    private Element getFirstMethod(JavacTask task, String typeName) {
-        return ElementFilter.methodsIn(task.getElements().getTypeElement(typeName).getEnclosedElements()).get(0);
-    }
-
-    private Function<JavacTask, Element> getSubTest = t -> getFirstMethod(t, "test.Sub");
-
     public void testInheritNoJavadoc() throws Exception {
         doTestJavadoc("",
                       getSubTest,
@@ -301,6 +295,150 @@ public void testShortComment() throws Exception {
                       "@return value\n");
     }
 
+    public void testMarkdown() throws Exception {
+        doTestJavadoc("""
+                      /// Prefix {@inheritDoc} suffix.
+                      ///
+                      /// *Another* __paragraph__.
+                      ///
+                      /// Paragraph \ufffc with \ufffc replacement \ufffc character.
+                      ///
+                      /// @param p1 prefix {@inheritDoc} suffix
+                      /// @param p2 prefix {@inheritDoc} suffix
+                      /// @param p3 prefix {@inheritDoc} suffix
+                      /// @throws IllegalStateException prefix {@inheritDoc} suffix
+                      /// @throws IllegalArgumentException prefix {@inheritDoc} suffix
+                      /// @throws IllegalAccessException prefix {@inheritDoc} suffix
+                      /// @return prefix {@inheritDoc} suffix
+                      """,
+                      getSubTest,
+                      """
+                      Prefix javadoc1 suffix.
+
+                      <p><em>Another</em> <strong>paragraph</strong>.
+
+                      <p>Paragraph \ufffc with \ufffc replacement \ufffc character.
+
+                      @param p1 prefix param1 suffix
+                      @param p2 prefix param2 suffix
+                      @param p3 prefix param3 suffix
+                      @throws IllegalStateException prefix exc1 suffix
+                      @throws IllegalArgumentException prefix exc2 suffix
+                      @throws IllegalAccessException prefix exc3 suffix
+                      @return prefix value suffix""");
+    }
+
+    public void testMarkdown2() throws Exception {
+        doTestJavadoc("""
+                      /// {@inheritDoc}
+                      ///
+                      /// *Another* __paragraph__. [java.lang.Object]
+                      ///
+                      /// @since snc
+                      """,
+                      getSubTest,
+                      """
+                      javadoc1
+
+                      <p><em>Another</em> <strong>paragraph</strong>. {@link java.lang.Object}
+
+                      @param p1 param1
+                      @param p2 param2
+                      @param p3 param3
+                      @throws java.lang.IllegalStateException exc1
+                      @throws java.lang.IllegalArgumentException exc2
+                      @throws java.lang.IllegalAccessException exc3
+                      @return value
+                      @since snc""");
+    }
+
+    public void testMarkdown3() throws Exception {
+        doTestJavadoc("""
+                      /// {@inheritDoc}
+                      ///
+                      /// *Another* __paragraph__.
+                      """,
+                      getSubTest,
+                      //the formatting could be improved:
+                      """
+                      javadoc1
+
+                      <p><em>Another</em> <strong>paragraph</strong>.@param p1 param1
+                      @param p2 param2
+                      @param p3 param3
+                      @throws java.lang.IllegalStateException exc1
+                      @throws java.lang.IllegalArgumentException exc2
+                      @throws java.lang.IllegalAccessException exc3
+                      @return value
+                      """);
+    }
+
+    public void testMarkdown4() throws Exception {
+        doTestJavadoc("""
+                      /// {@inheritDoc}
+                      ///
+                      /// *Another* __paragraph__. [test][java.lang.Object]
+                      ///
+                      /// @since snc
+                      """,
+                      getSubTest,
+                      """
+                      javadoc1
+
+                      <p><em>Another</em> <strong>paragraph</strong>. {@linkplain java.lang.Object test}
+
+                      @param p1 param1
+                      @param p2 param2
+                      @param p3 param3
+                      @throws java.lang.IllegalStateException exc1
+                      @throws java.lang.IllegalArgumentException exc2
+                      @throws java.lang.IllegalAccessException exc3
+                      @return value
+                      @since snc""");
+    }
+
+    public void testMarkdown5() throws Exception {
+        doTestJavadoc("""
+                      ///[define classes][java.lang.invoke.MethodHandles.Lookup#defineClass(byte\\[\\])]
+                      ///
+                      /// @since snc
+                      """,
+                      getSubTest,
+                      """
+                      {@linkplain java.lang.invoke.MethodHandles.Lookup#defineClass(byte[]) define classes}
+
+                      @param p1 param1
+                      @param p2 param2
+                      @param p3 param3
+                      @throws java.lang.IllegalStateException exc1
+                      @throws java.lang.IllegalArgumentException exc2
+                      @throws java.lang.IllegalAccessException exc3
+                      @return value
+                       @since snc""");
+    }
+
+    public void testMarkdown6() throws Exception {
+        doTestJavadoc("""
+                      ///Text1 [define classes][java.lang.invoke.MethodHandles.Lookup#defineClass(byte\\[\\])]
+                      ///text2
+                      ///
+                      /// @since snc
+                      """,
+                      getSubTest,
+                      """
+                      Text1 {@linkplain java.lang.invoke.MethodHandles.Lookup#defineClass(byte[]) define classes}
+                      text2
+
+                      @param p1 param1
+                      @param p2 param2
+                      @param p3 param3
+                      @throws java.lang.IllegalStateException exc1
+                      @throws java.lang.IllegalArgumentException exc2
+                      @throws java.lang.IllegalAccessException exc3
+                      @return value
+                       @since snc""");
+    }
+
     private void doTestJavadoc(String origJavadoc, Function<JavacTask, Element> getElement, String expectedJavadoc) throws Exception {
         doTestJavadoc(origJavadoc,
                       "    /**\n" +
@@ -370,6 +508,12 @@ private void doTestJavadoc(String origJavadoc,
         }
     }
 
+    private Element getFirstMethod(JavacTask task, String typeName) {
+        return ElementFilter.methodsIn(task.getElements().getTypeElement(typeName).getEnclosedElements()).get(0);
+    }
+
+    private Function<JavacTask, Element> getSubTest = t -> getFirstMethod(t, "test.Sub");
+
     private static final class JFOImpl extends SimpleJavaFileObject {
 
         private final String code;