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

[Pavel Rappo]

On Wed, 8 Nov 2023 15:57:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since the last revision:
>> 
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> test/langtools/tools/javac/doctree/DocCommentTester.java line 1012:
> 
>> 1010: //            }
>> 1011: //            return null;
>> 1012: //        }
> 
> Debugging leftover?

If you want to leave it for debugging you can make it private and uncomment.

> test/langtools/tools/javac/doctree/MarkdownTest.java line 555:
> 
>> 553: //  block tags: empty
>> 554: //]
>> 555: //*/
> 
> Just to clarify: it is supposed to be commented out, right? If uncommented, this test fails with a slightly different error.

Please update the DocComment printout in that commented out test: the actual content is different. It would be nice if the test were passing at least at the moment of its initial commit.

Here's what I see locally:


Expect:
DocComment[DOC_COMMENT, pos:0
  firstSentence: 1
    Summary[SUMMARY, pos:4
      summary: 1
        Erroneous[ERRONEOUS, pos:14, prefPos:37
          code: compiler.err.dc.unterminated.inline.tag
          body: abc_`|_def}|_rest_`more`
        ]
    ]
  body: empty
  block tags: empty
]

Found:
DocComment[DOC_COMMENT, pos:0
  firstSentence: 1
    Summary[SUMMARY, pos:1
      summary: 1
        Erroneous[ERRONEOUS, pos:11, prefPos:32
          code: compiler.err.dc.unterminated.inline.tag
          body: abc_`|def}|rest_`more`
        ]
    ]
  body: empty
  block tags: empty
]

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

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