RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]

[Jonathan Gibbons]

On Tue, 30 Jan 2024 22:55:27 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java line 238:
>> 
>>> 236:                         && postamble.isEmpty()
>>> 237:                         && fullBody.stream().anyMatch(t -> t.getKind() == Kind.MARKDOWN)
>>> 238:                         ? CommentStyle.JAVADOC_LINE : CommentStyle.JAVADOC_BLOCK;
>> 
>> While clever, it seems to be prone to false positive `JAVADOC_LINE`. Also, it is inconsistent with `null` and `Position.NOPOS` returned from the `getText` and `getSourcePos(int)` methods respectively.
>
> I'm not worried about false positive `JAVADOC_LINE` than maybe false _negative_ `JAVADOC_LINE`.  Generally, the underlying issue here is how to handle weird combinations of `DocTrees` constructed by a user of the public API.  For example, should we check, and reject, a `fullBody` containing `MARKDOWN` nodes and non-empty  `preamble` or `postamble`, since that combination will never come from `DocCommentParser`.
> 
> I'm not worried about comparison with `getText` and `getSourcePos`, since there really is no other value for the source text or source position that we can return. But we can infer a best guess for the style.
> 
> Arguably, we should check the `tags` as well.
> 
> ------
> 
> I dug deeper.
> 
> We do create synthetic trees in the standard doclet, such as for the descriptions of mandated methods (like `values` and `valueOf` for any enum class.  Those synthetic trees do utilize this code path, although the `getStyle` method is not currently invoked. (Verified by changing code to throw `UnsupportedOperationException` and run all the tests.) It's also true those synthetic trees do not leverage any Markdown support at this time.
> 
> I prefer to leave the code as-is at this time.

I revisited this, and rewrote the code and added more comments for now and for later.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473474540