JDK-8310172 : Use directed inheritDoc for javax.lang.model API
  • Type: CSR
  • Component: core-libs
  • Sub-Component: javax.lang.model
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 22
  • Submitted: 2023-06-15
  • Updated: 2023-06-16
  • Resolved: 2023-06-16
Related Reports
CSR :  
Description
Summary
-------

Use the new directed inheritance feature of `@inheritDoc` to improve the structure of the javadoc in `javax.lang.model` and `javax.annotation.processing`.

Problem
-------

Un-directed  `@inheritDoc` is imprecise in its meaning. A refactoring pass to use  `@inheritDoc` revealed several minor spec bugs and areas for improvement.

Solution
--------

Systematically adopt directed `@inheritDoc`. The actual changes to the API are smaller than the patch would suggest; the updates in the rendered javadoc are:

* Improvements to general spec vs implSpec for `AbstractProcessor`
* Minor update to `AbstractTypeVisitor8`
* Add explicit visitRecordComponent  override to ElementScanner6; this changes where `ElementScanner{7, 8, 9, 14}` inherit the method from
* `SimpleTypeVisitor6:` remove redundant text that was previous moved to an `implSpec` tag.
* Add explicit throws tag to `AbstractAnnotationValueVisitor6.visitUnknown`

Specification
-------------

See attached specdiff JDK-8309964.specdiff.1.zip
Comments
Moving to Approved.
16-06-2023