RFR: JDK-8267126: javadoc should show "line and caret" for diagnostics. [v2]

[Jonathan Gibbons]

On Mon, 24 May 2021 18:40:26 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java line 543:
>> 
>>> 541:      * Returns whether or not to permit dynamically loaded components to access
>>> 542:      * part of the javadoc internal API. The flag is the same (hidden) compiler
>>> 543:      * option that allows javac plugins and annotation processors to javac internal
>> 
>> Do you use "allow x to y" here in the sense of "letting x into y"? If so, consider using "allow x into y" instead of "allow x to y". Otherwise it might sound like there's a verb missing: allow to (access? enter?) javac internal API. My non-native English speaker's two cents.
>
> Yes, there was a missing verb. Fixed.

(Copyrights: only TagletManager needed updating; done.)

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Messager.java line 92:
>> 
>>> 90:  *     <li>{@code Diagnostic.Kind} -- maps to {@code DiagnosticType} and {@code Set<DiagnosticFlag>}
>>> 91:  *     <li>{@code Element} -- maps to {@code DiagnosticSource and {@code DiagnosticPosition}
>>> 92:  *     <li>{@code DocTreePath} -- maps to {@code DiagnosticSource and {@code DiagnosticPosition}
>> 
>> Close `@code` tags.
>
> oops

mildly worrying that "make docs" did not give errors  ... but I guess the error was masked by the subsequent `}` of the subsequent `{@code ...}`

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Messager.java line 96:
>> 
>>> 94:  *
>>> 95:  * The javac layer deals primarily in pre-localized (key, args) pairs,
>>> 96:  * while the javadoc layer, especially the {@code Reporter} interface, deals in localized strings.
>> 
>> If it is not a typo, consider changing "deal in" to something simpler.
>
> I'll try.  Maybe something based on "operates on" or "uses" or something.

Rephrased the sentence and added more details as well.

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

PR: https://git.openjdk.java.net/jdk/pull/4074