RFR: 8338596: Clarify handling of restricted and caller-sensitive methods [v5]

[Pavel Rappo]

On Mon, 23 Sep 2024 21:03:08 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix javadoc test failure
>
> test/langtools/jdk/javadoc/doclet/testRestricted/TestRestricted.java line 45:
> 
>> 43:     public static void main(String... args) throws Exception {
>> 44:         var tester = new TestRestricted();
>> 45:         tester.setAutomaticCheckLinks(false);
> 
> @hns I had to disable this check because otherwise the test framework will attempt (and fail) to resolve `../java.base/java/lang/doc-files/RestrictedMethods.html`. Is there a better way to do this w/o disabling the link checks?

I'm not Hannes, but to my mind, the fact that you had to disable that check to make the test pass hints that it's a real problem rather than a minor inconvenience.

Basing this URL off `{@docRoot}` seems an incorrect thing to do:

    doclet.Restricted.url={@docRoot}/java.base/java/lang/doc-files/RestrictedMethods.html

It will only be `@docRoot` in the JDK, but not in any other code base, and certainly not in that test.

I don't know if restricted methods is a JDK-only feature, but for javadoc's sake, we should treat it like it's not. So the link should go to the same place where `{@link Object}` goes.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1787962609