RFR: JDK-8298405: Support Markdown in the standard doclet [v5]

Jimisola Laursen duke at openjdk.org
Tue Feb 21 05:28:43 UTC 2023

On Tue, 7 Feb 2023 19:42:39 GMT, Jonathan Gibbons <jjg at openjdk.org> 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.
>> Background info: https://mail.openjdk.org/pipermail/javadoc-dev/2023-January/005563.html
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 10 commits:
>  - Merge with upstream/master
>  - Rename MarkdownTree to RawTextTree
>  - Merge with upstream/master
>  - Update copyright years
>  - Rename FFFC variable
>    Share Markdown parser and renderer in instance of MarkdownHandler
>  - Move CommonMark to new internal module.
>    Add legal header to imported CommonMark source files
>    Always use Text nodes inside AttributeTree values
>    Unwrap <p> from "simple" paragraphs
>  - Always use Text nodes inside AttributeTree values
>  - Update to CommonMark 0.21.
>  - fix whitespace
>  - JDK-8298405: Markdown support in the standard doclet

Would also really like to see AsciiDoc support. Our development team use it for everything. Markdown is ok but AsciiDoc is much better for technical documentation.

What is necessary for AsciiDoc to be considered? Or rather, what is the process for it being taken into consideration?


PR: https://git.openjdk.org/jdk/pull/11701

More information about the compiler-dev mailing list