On Mon, 13 Mar 2023 09:58:51 GMT, Alan Bateman <al...@openjdk.org> wrote:
>> Joe Wang has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> clean up tests; fix copy&paste error.
>
> src/java.xml/share/classes/javax/xml/XMLConstants.java line 247:
>
>> 245: * <a
>> href="../../module-summary.html#ConfigurationFile">configuration file</a>.
>> 246: * If the file exists and the system property is specified, its
>> value will
>> 247: * be used to override the default of the property.
>
> This follows the documenting of the equivalent system property but that text
> doesn't say what it overrides. I think it overrides the default value but
> does not override programmatic use. The new text documents that the
> configuration file can be used. It is a bit clearer that it overrides the
> default value but doesn't say anything about programmatic use. The reader
> will also wonder if the system property overrides the configuration file or
> the other way around. So I think my point is that the precedent needs to
> clearly documented, maybe it document the ordering in one place and have each
> property reference it. In the case of XMLConstants, then it might also be
> simpler to put the text in the class description rather than having it
> repeated in every property - maybe experiment with that to see if it helps or
> not.
>
> In passing, I assume these links can be use
> `{@docRoot}/java.xml/module-summary.html`.
I'll rewrite the "configuration file" section in the module description to
include a general override procedure to discuss "scope and order" and have
these properties point to that.
Thanks for the pointer, that link to the module-summary looks cleaner.
-------------
PR: https://git.openjdk.org/jdk/pull/12985
