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

[Joe Darcy]

Thanks for the review Jon; will push with "<strong>".

-Joe

On 2/25/2020 5:28 PM, Jonathan Gibbons wrote:
> Looks good to me.
>
> I also understand your intention to use textual semantic formatting in 
> the same sentence as typographic formatting, so also OK if you'd 
> prefer to use <em> or <strong> for "after".
>
> -- Jon
>
>
> On 02/25/2020 04:03 PM, Joe Darcy wrote:
>> 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
>>>>
>