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

[Hannes Wallnöfer]

On Fri, 4 Oct 2024 16:32:50 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

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

Sorry for missing the mention. I agree with @pavelrappo that this doesn't look quite right. It's true that it is not usually an issue as the feature will not be used outside of Java SE APIs. But it's conceivable that builds API docs for JDK or Java SE modules without including `java.base`. I think the right solution would be to create the link only if `java.base`/`java.lang` is included in the documentation.

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

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