On Tue, 3 Jan 2023 19:56:51 GMT, Pavel Rappo <[email protected]> wrote:
>> Support for Markdown comments in the standard doclet.
>>
>> To enable Markdown in a comment, start the comment with `/**md` followed by
>> whitespace. The syntax is as defined for CommonMark.
>>
>> The work is in 3 parts:
>>
>> 1. Update the Compiler Tree API to support Markdown tree nodes, containing
>> strings of (uninterpreted) Markdown source code.
>> 2. Import commonmark-java into the `jdk.javadoc` module, to be able to
>> convert Markdown strings to HTML.
>> 3. Update the standard doclet, to leverage the preceding two parts, to
>> translate Markdown in documentation comments to `Content` nodes.
>>
>> There are new tests both for the low level work in the Compiler Tree API,
>> and for the overall high-level work in the doclet.
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java line 158:
>
>> 156: /**
>> 157: * Used for instances of {@link MarkdownTree}
>> 158: * representing a fragment of Markdown code.
>
> _Markdown code_: is there a better term for a run/span/block of Markdown?
> Here and elsewhere in this PR, _Markdown code_ reads slightly weird and
> misleading.
I agree it is not great. For some reason, I wanted to stay clear of *Markdown
text* as being a source of confusion for the plain non-markup content in a
String containing Markdown content.
I'll look at the Markdown/CommonMark spec for any precedent. Failing that, I
will at least try and ensure the terminology that we use is consistent.
-------------
PR: https://git.openjdk.org/jdk/pull/11701
