RFR: JDK-8268420: new Reporter method to report a diagnostic within a DocTree node [v3]

[Pavel Rappo]

On Thu, 8 Jul 2021 18:48:30 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review an update to add a new method in Reporter to report a diagnostic within a DocTree node for those DocTree nodes that wrap a string.
>> 
>> This is the last of the current round of updates to improve the diagnostics that can be generated by javadoc.
>> 
>> The general fix, in JavadocLog and Reporter, is pretty simple, given all the improvements in recent related changes.
>> 
>> There are some cosmetic cleanups that were made while exploring the current solution.
>> 
>> The test is "reasonably thorough" and uses a custom taglet to generate diagnostics for selected nodes in doc comment trees. The test then "algorithmically validates" (i.e. no golden files or text blocks) the diagnostics that are either passed to a DiagnosticListener or written to the console stream.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains five additional commits since the last revision:
> 
>  - Update Reporter spec; add methods to Messages
>  - Merge remote-tracking branch 'upstream/master' into 8268420.Reporter-DocTree-pos
>  - Merge remote-tracking branch 'upstream/master' into 8268420.Reporter-DocTree-pos
>  - Address review feedback
>  - JDK-8268420
>    new Reporter method to report a diagnostic within a DocTree node

Please address the earlier comments https://github.com/openjdk/jdk/pull/4489#discussion_r653797909 and https://github.com/openjdk/jdk/pull/4489#discussion_r653799103.

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java line 99:

> 97:      * @implNote
> 98:      * This implementation ignores the {@code (start, pos, end)} values and simply calls
> 99:      * {@link #print(Diagnostic.Kind, DocTreePath,String) print(kind, path, message)};

Is there a particular reason for that trailing `;` ? Shouldn't there be `.` instead?

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

Changes requested by prappo (Reviewer).

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