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

[Jonathan Gibbons]

Joe,

Generally OK.

Use of "That is," seems very idiomatic.

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>

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

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