On Fri, 4 Oct 2024 16:32:50 GMT, Pavel Rappo <pra...@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
