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

[Pavel Rappo]

On Thu, 11 Jan 2024 15:07:33 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> test/langtools/tools/javac/classfiles/attributes/deprecated/DeprecatedTest.java line 26:
>> 
>>> 24: /*
>>> 25:  * @test
>>> 26:  * @bug 8042261 8298405
>> 
>> This comment is not for this line, but for two compiler tests for `@deprecated` javadoc tag. It seemed quite contextual place to put it.
>> 
>> Did I miss it, or you are planning to add a javadoc test that verifies that `@deprecated` appearing in a `///` comment has no [special meaning] it has in classic `/** */` comments?
>> 
>> [special meaning]: https://github.com/openjdk/jdk/blob/128363bf3b57dfa05b3807271b47851733c1afb9/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java#L1639-L1653
>
> Ping. I do believe that it's important to have such a test.

Ping.

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

Ping.

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

Ping.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483179667
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483179302
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483178073