JDK 15 initial RFR of 8193553: Provide better guidance on using javax.lang.model visitors

[Joe Darcy]

Hi Jon,

Revised webrev with updates to all three top-level visitor interfaces:

     http://cr.openjdk.java.net/~darcy/8193553.1/

Comments below.

On 2/25/2020 9:58 AM, Jonathan Gibbons wrote:
> Joe,
>
> Generally OK.
>
> Use of "That is," seems very idiomatic.


Changed "This is" to "In particular"; in context:


     "The families follow a naming pattern along the lines of 
FooVisitorN where N indicates the source version the visitor is 
appropriate for. In particular, a FooVisitorN is expected to handle all 
language constructs present in source version "


>
> You have a mix of <em> and <i> in the same sentence
> Either stay semantic and use <em> and <strong> or typographic <i> and <b>


The N's should be in italics, hence the <i> tags. I've change the other 
tag to <b> to be locally consistent, but <em> was the intention.


>
> I'm not a big fan of pluralizing types in links, as in {@link Foo}s  
> but it's not awful.


Just to be clear, the plurals in this case refers to a family of types 
such as AbstractElementVisitor6, AbstractElementVisitor7, 
AbstractElementVisitor8, AbstractElementVisitor9, and 
AbstractElementVisitor14. The link is to the earliest member of the 
family; I don't know of a good way to have a collective link to these 
sets of types, but want to refer to them collectively at least in the text.

Thanks,

-Joe


>
> -- Jon
>
> On 2/21/20 9:38 AM, Joe Darcy wrote:
>> Hello,
>>
>> Please review the initial fix for
>>
>>     8193553 : Provide better guidance on using javax.lang.model visitors
>>     http://cr.openjdk.java.net/~darcy/8193553.0/
>>
>> Once wording is agree to for the element visitor case, I'll write 
>> analogous additions for the type visitor and annotation value visitor 
>> classes and send around the set of changes for another round of review.
>>
>> Thanks,
>>
>> -Joe
>>
>> --- 
>> old/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
>> 2020-02-21 09:33:06.898482673 -0800
>> +++ 
>> new/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
>> 2020-02-21 09:33:06.598482673 -0800
>> @@ -64,6 +64,53 @@
>>   * packages that are only required to run on Java SE 8 and higher
>>   * platform versions.
>>   *
>> + * @apiNote
>> + *
>> + * There are several families of classes implementing this visitor
>> + * interface in the {@linkplain javax.lang.model.util util
>> + * package}. The families follow a naming pattern along the lines of
>> + * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the
>> + * {@linkplain javax.lang.model.SourceVersion source version} the
>> + * visitor is appropriate for.
>> + *
>> + * That is, a {@code FooVisitor}<i>N</i> is expected
>> + * to handle all language constructs present in source version
>> + * <i>N</i>. If there are no new language constructs added in version
>> + * <i>N</i> + 1 (or subsequent releases), {@code
>> + * FooVisitor}<i>N</i> may also handle that later source version; in
>> + * that case, the {@link
>> + * javax.annotation.processing.SupportedSourceVersion
>> + * SupportedSourceVersion} annotation on the {@code
>> + * FooVisitor}<i>N</i> class will indicate a later version.
>> + *
>> + * When visiting an element representing a language construct
>> + * introduced <em>after</em> source version <i>N</i>, a {@code
>> + * FooVisitor}<i>N</i> will throw an {@link UnknownElementException}
>> + * unless that behavior is overridden.
>> + *
>> + * <p>When choosing which member of a visitor family to subclass,
>> + * subclassing the most recent one increases the range of source
>> + * versions covered. When choosing which visitor family to subclass,
>> + * consider their built-in capabilities:
>> + *
>> + * <ul>
>> + *
>> + * <li>{@link AbstractElementVisitor6 AbstractElementVisitor}s:
>> + * Skeletal visitor implementations.
>> + *
>> + * <li>{@link SimpleElementVisitor6 SimpleElementVisitor}s: Support
>> + * default actions and a default return value.
>> + *
>> + * <li>{@link ElementKindVisitor6 ElementKindVisitor}s: Visit methods
>> + * provided on a {@linkplain Element#getKind per-kind} granularity as
>> + * some categories of elements can have more than one kind.
>> + *
>> + * <li>{@link ElementScanner6 ElementScanner}s: Scanners are visitors
>> + * which traverse an element and the elements {@linkplain
>> + * Element#getEnclosedElements enclosed} by it and associated with it.
>> + *
>> + * </ul>
>> + *
>>   * @param <R> the return type of this visitor's methods. Use {@link
>>   *            Void} for visitors that do not need to return results.
>>   * @param <P> the type of the additional parameter to this visitor's
>>