RFR: 8325168: JShell should support Markdown comments

[Jonathan Gibbons]

On Fri, 2 Feb 2024 14:02:28 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> This is an attempt to add Markdown support in documentation comments to JShell.
> 
> It works by converting the Markdown text to HTML during the process of resolving `{@inheritDoc}` tags.

Changes requested by jjg (Reviewer).

Compared to the previous PR, which was reasonably simple and quite elegant,
this one seems unduly complicated and somewhat invasive. It is also using
the transformer mechanism in a way that is not as intended. 

The `jdk.internal.md` module is intended to be for JDK support for Markdown.
As such, it has an imported copy of `commonmark-java` and now the new transformer
support, which is just intended to be used to support any JDK extensions to Markdown,
such as the new support for reference links for program elements. (There are 
suggestions for other future features in the JEP.) As such, I would 
expect all JDK clients to use the existing "standard" transformer, and to not 
substitute their own.  Ideally, the "standard" transformer would be used
by default, but I wanted to avoid an unconditional dependency from `jdk.compiler`
to `jdk.internal.md` -- so hence the use of the service provider mechanism.
(I guess I could update `jdk.compiler` to use `requires static` to establish
a compile-time dependency on the `jdk.internal.md` module, and then try
and install the standard transformer, which would always be available if we
put a hard dependency in modules like `jdk.javadoc` and `jdk.jshell`.)

Your previous PR was pretty good (although I accept we did not get as far as
a full review and approval.)  The recent changes the overall Markdown work
were made with that PR in mind.  As such, the intention was that only two
fairly small changes would be required.

1. Change the means to detect Markdown comments, from looking for `/**md`
   to using the new `CommentKind` support in `DocTrees`.
2. Install the 'standard' transformer, to enable the JDK extensions to
   Markdown

With those two changes, you can use the previous technique to parse and 
render a Markdown doc comment as before.

src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/JavadocHelper.java line 95:

> 93: import com.sun.tools.javac.util.DefinedBy.Api;
> 94: import com.sun.tools.javac.util.Pair;
> 95: import java.util.ServiceLoader;

out of order; suggest moving to be with other `java.*` imports

src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/JavadocHelper.java line 261:

> 259:                 @Override
> 260:                 public Void scan(Iterable<? extends DocTree> nodes, Void p) {
> 261:                     return super.scan(nodes, p); // Generated from nbfs://nbhost/SystemFileSystem/Templates/Classes/Code/OverriddenMethodBody

I'm not sure what to do with that comment.

-------------

PR Review: https://git.openjdk.org/jdk/pull/17686#pullrequestreview-1860164867
PR Comment: https://git.openjdk.org/jdk/pull/17686#issuecomment-1927843621
PR Review Comment: https://git.openjdk.org/jdk/pull/17686#discussion_r1476580909
PR Review Comment: https://git.openjdk.org/jdk/pull/17686#discussion_r1476583652