On Thu, 27 May 2021 10:15:43 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> Please review an update to `jdk.javadoc/jdk.javadoc.doclets.Reporter` to add
>> 3 new methods and to improve the descriptions of other parts of the
>> interface.
>>
>> The new methods provide access to the underlying streams (informally, for
>> standard output and diagnostic output), and a new `report` method to report
>> diagnostics at an arbitrary position in a file being read by a doclet, or a
>> taglet within a doclet.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java line 98:
>
>> 96: * @param file the file
>> 97: * @param start the beginning of the enclosing range
>> 98: * @param pos the position
>
> Unless there's a reason not to, I would prefer to have an inequality clearly
> showing how these 3 indexes relate to each other. For example, is it the case
> that `{@code start <= pos <= end}`?
Will do. I had this in an earlier draft. I backed out because I also wanted to
bound `start` and `end` but it is not common in API to indicate indices must be
non-negative, and it is an IO operation (and potential exception) to verify the
upper bound is valid.
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Messager.java line
> 435:
>
>> 433:
>> 434: /**
>> 435: * Prints the error and warning counts, if any, to. the diagnostic
>> writer
>
> Move period from after "to" to the end of the sentence.
Wow, how did that typo come about? :-)
-------------
PR: https://git.openjdk.java.net/jdk/pull/4216
