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

[Jonathan Gibbons]

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
>>>