Re: RFR: 8285368: Overhaul doc-comment inheritance [v8]

2023-06-13 Thread Pavel Rappo 
On Thu, 8 Jun 2023 14:47:13 GMT, Pavel Rappo  wrote:

>> Please review this long-awaited change to documentation inheritance.
>> 
>> This change improves "methods comment algorithm" and introduces directed 
>> documentation inheritance. While "methods comment algorithm" -- automatic 
>> search for inheritable documentation -- has been improved, it still cannot 
>> read an author's mind so as to always find the documentation they intended. 
>> From now on, an author can state their intention, by providing an FQN of the 
>> superclass or superinterface from which to inherit documentation:
>> 
>> ​{@inheritDoc S}
>> 
>> Which is exactly what I did to counterbalance some of the JDK API 
>> Documentation changes caused by the change to "methods comment algorithm".
>
> Pavel Rappo has updated the pull request incrementally with one additional 
> commit since the last revision:
> 
>   feedback: use JavadocTester.out
>   
>   Also, trivially fixes grammar (word order) in a comment.

core-libs, client: any reviewers?

-

PR Comment: https://git.openjdk.org/jdk/pull/14357#issuecomment-1588987444

Re: RFR: 8285368: Overhaul doc-comment inheritance [v8]

2023-06-08 Thread Pavel Rappo 
> Please review this long-awaited change to documentation inheritance.
> 
> This change improves "methods comment algorithm" and introduces directed 
> documentation inheritance. While "methods comment algorithm" -- automatic 
> search for inheritable documentation -- has been improved, it still cannot 
> read an author's mind so as to always find the documentation they intended. 
> From now on, an author can state their intention, by providing an FQN of the 
> superclass or superinterface from which to inherit documentation:
> 
> ​{@inheritDoc S}
> 
> Which is exactly what I did to counterbalance some of the JDK API 
> Documentation changes caused by the change to "methods comment algorithm".

Pavel Rappo has updated the pull request incrementally with one additional 
commit since the last revision:

  feedback: use JavadocTester.out
  
  Also, trivially fixes grammar (word order) in a comment.

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/14357/files
  - new: https://git.openjdk.org/jdk/pull/14357/files/dea776e2..cccffa66

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=14357=07
 - incr: https://webrevs.openjdk.org/?repo=jdk=14357=06-07

  Stats: 6 lines in 1 file changed: 0 ins; 0 del; 6 mod
  Patch: https://git.openjdk.org/jdk/pull/14357.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/14357/head:pull/14357

PR: https://git.openjdk.org/jdk/pull/14357