RFR: JDK-8298405: Markdown support in the standard doclet

[Jonathan Gibbons]

On Wed, 4 Jan 2023 19:50:01 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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.

A quick simplistic scan of the CommonMark spec reveals no clear winner.


   2 Markdown and
   1 Markdown code
   1 Markdown content
   1 Markdown counts
   1 Markdown document
   2 Markdown documents
   2 Markdown from
   1 Markdown have
   5 Markdown implementations
   1 Markdown inline
   2 Markdown is
   1 Markdown meanings
   1 Markdown paragraph
   1 Markdown practice
   1 Markdown program
   1 Markdown spec
   1 Markdown started
   6 Markdown syntax
   1 Markdown to
   1 Markdown treats
   1 Markdown version
   1 Markdown will
   1 Markdown with


Of these, `content`, `document` and `program` seem the most applicable.

* `content` has the potential for confusion with the `javadoc` `Content` class ... but we already cope with `Element` and `Tag` by leveraging qualifying adjectives.
* `document` seems to imply a file full of content, and not the content of (part of) a doc comment
* `program` seems too geeky.

Of the choices, `content` seems most reasonable.

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

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