On Fri, 2 Feb 2024 14:02:28 GMT, Jan Lahoda <jlah...@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
