On Wed, 4 Jan 2023 19:50:01 GMT, Jonathan Gibbons <j...@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
