RFR: 8216497: javadoc should auto-link to platform classes [v2]

[Hannes Wallnoefer]

Switching to reply by email to javadoc-dev only in order to not spam all the other mailing lists with each comment/reply.

> Am 22.09.2020 um 19:37 schrieb Jonathan Gibbons <jjg at openjdk.java.net>:
> 
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 350:
> 
>> 348:
>> 349: doclet.usage.excludedocfilessubdir.parameters=\
>> 350:     <name>:..
> 
> 3 dots for ellipsis?   2 dots is "parent directory"

That is outside the scope of this changeset. Should I include the fix regardless? 

> 
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 384:
> 
>> 382:
>> 383: doclet.usage.no-platform-link.description=\
>> 384:     Do not generate links to platform documentation
> 
> Suggest:
> Do not generate links to the platform documentation

Changed in next commit.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 194:
> 
>> 192:
>> 193:     /**
>> 194:      * Argument for command-line option {@code --no-platform-link}.
> 
> minor: would "--no-platform-links" (plural) be a better name for the option?
> 
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 435:
> 
>> 433:                 },
>> 434:
>> 435:                 new Option(resources, "--no-platform-link") {
> 
> Repeating preceding comment: would `--no-platform-links` (plural) be a better name?

Yes, I think `--no-platform-links` is a better name, although it will require some changes in tests and CSR. 
I guess it helped to convince me that you asked twice :)

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java line 236:
> 
>> 234:      * @param linkPlatformProperties path or URL to properties file containing
>> 235:      *                               platform documentation URLs, or null
>> 236:      * @param reporter The {@code DocErrorReporter} used to report errors.
> 
> (pedantic) param descriptions are typically phrases (no initial capital, no trailing period)
> In this case, your two `@param` descriptions are inconsistent
> 

Fixed.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java line 323:
> 
>> 321:                 props.load(inputStream);
>> 322:             }
>> 323:             url = props.getProperty("doclet.platform.docs." + version);
> 
> Similar to other file-or-url arguments: good!
> 
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java line 340:
> 
>> 338:     private int getSourceVersionNumber() {
>> 339:         SourceVersion sourceVersion = configuration.docEnv.getSourceVersion();
>> 340:         // TODO it would be nice if this was provided by SourceVersion
> 
> File an RFE for `SourceVersion`

Will do.

> test/langtools/jdk/javadoc/doclet/testAnnotationTypes/TestAnnotationTypes.java line 49:
> 
>> 47:         javadoc("-d", "out-1",
>> 48:                 "-sourcepath", testSrc,
>> 49:                 "--no-platform-link",
> 
> I see lots of instances of `no-platform-link` in this and subsequent tests. `JavadocTester` does have the concept of
> default options, although that may be more for the behavior after executing javadoc and not for the options given to
> javadoc itself. Is it worth supporting default javadoc options, since that the default can be disabled for specific
> tests?

I answered that one in a separate comment on github already, to recap: I couldn’t find the default options mechanism 
in JavadocTester, and I’m afraid it will be detrimental for transparency and usability of the class.

Hannes

> -------------
> 
> PR: https://git.openjdk.java.net/jdk/pull/171