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

Jonathan Gibbons jjg at openjdk.org
Thu Feb 8 21:01:00 UTC 2024


On Thu, 8 Feb 2024 15:37:06 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Ping. I do believe that it's important to have such a test.
>
> Ping.

I believe this is substantially covered in line 226-227.  See the third call to `test` in the following group of lines:


for (String src : sources) {
                test(src);
                test(src.replaceAll("@Deprecated", "/** @deprecated */"));
                test(src.replaceAll("deprecated", "notDeprecated2") // change class name
                        .replaceAll("@Deprecated", "/// @deprecated\n"));
            }


* The first call, `test(src)`, runs all the test cases, using the `@Deprecated` annotation by default.  In these test cases, the name of the element encodes whether it is expected that the element is deprecated or not.

* The second call, `test(src.replaceAll("deprecated", "notDeprecated2")`, runs the test cases again, after changing the annotation to a traditional (`/** ...*/`) comment containing the `@deprecated` tag. This is a long-standing call, and tests the legacy behavior of `@deprecated` appearing in a traditional doc comment.  Effectively, it tests whether a `/** @deprecated */` comment has equivalent behavior to a `@Deprecated` comment.

* The third call is new to this PR and the functionality to support Markdown comments.  It makes two changes to the source for the test cases, before running them:
   1. as in the previous test, the annotations are replaced by a comment containing `@deprecated` -- except that this time, the comment is a new-style `/// ... ` comment instead of a traditional `/** ... */` comment, and ...
   2. because we do not expect `/// @deprecated` to indicate deprecation, we need to change the expected result for each test case, which we do by changing the element name for the test case.  The change is the first call to replace to avoid false positives after changing the doc comment. The change uses a new name, `notDeprecated2`, in which `notDeprecated` encodes the expected deprecation status, and the `2` is to differentiate the declarations from other declarations in the case case that already use the name `notDeprecated`.

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

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


More information about the build-dev mailing list