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