Skip to content
Permalink
Browse files

8193553: Provide better guidance on using javax.lang.model visitors

Reviewed-by: jjg
  • Loading branch information
jddarcy committed Feb 26, 2020
1 parent 934db29 commit bdc481e96d591adf716aa953132c8b79d27834bb
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -27,9 +27,8 @@


import java.util.List;

import javax.lang.model.type.TypeMirror;

import javax.lang.model.util.*;

/**
* A visitor of the values of annotation type elements, using a
@@ -73,6 +72,46 @@
* 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.
*
* In particular, 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>&nbsp;+&nbsp;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 annotation value representing a language construct
* introduced <strong>after</strong> source version <i>N</i>, a {@code
* FooVisitor}<i>N</i> will throw an {@link
* UnknownAnnotationValueException} 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 AbstractAnnotationValueVisitor6
* AbstractAnnotationValueVisitor}s: Skeletal visitor implementations.
*
* <li>{@link SimpleAnnotationValueVisitor6
* SimpleAnnotationValueVisitor}s: Support default actions and a
* default return value.
*
* </ul>
*
* @param <R> the return type of this visitor's methods
* @param <P> the type of the additional parameter to this visitor's methods.
* @author Joseph D. Darcy
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -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.
*
* In particular, 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>&nbsp;+&nbsp;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 <strong>after</strong> 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
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
package javax.lang.model.type;

import javax.lang.model.element.*;
import javax.lang.model.util.*;

/**
* A visitor of types, in the style of the
@@ -64,6 +65,49 @@
* 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.
*
* In particular, 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>&nbsp;+&nbsp;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 a type representing a language construct
* introduced <strong>after</strong> source version <i>N</i>, a {@code
* FooVisitor}<i>N</i> will throw an {@link UnknownTypeException}
* 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 AbstractTypeVisitor6 AbstractTypeVisitor}s:
* Skeletal visitor implementations.
*
* <li>{@link SimpleTypeVisitor6 SimpleTypeVisitor}s: Support
* default actions and a default return value.
*
* <li>{@link TypeKindVisitor6 TypeKindVisitor}s: Visit methods
* provided on a {@linkplain TypeMirror#getKind per-kind} granularity
* as some categories of types can have more than one kind.
*
* </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

0 comments on commit bdc481e

Please sign in to comment.