RFR: 8329644: Discuss expected visitor evolution patterns in javax.lang.model.util

[Pavel Rappo]

On Tue, 16 Apr 2024 23:34:06 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Provide more concrete discussion of how the preview visitors are expected to evolve for different categories of language changes.

I have a few inline comments and a dumb question. The question: what happens if a preview feature exits the preview stage without being promoted to the standard, i.e. the preview feature is dropped?

src/java.compiler/share/classes/javax/lang/model/util/package-info.java line 50:

> 48:  * <p>The remainder of this note will show two examples of the API
> 49:  * changes in the model and visitors that can be added to support a
> 50:  * language feature. The examples will uses additions to the

Suggestion:

 * language feature. The examples will use additions to the

src/java.compiler/share/classes/javax/lang/model/util/package-info.java line 82:

> 80:  *  }
> 81:  * </pre>
> 82:  * A new element kind would also be introduce to model such a feature:

Suggestion:

 * A new element kind would also be introduced to model such a feature:

src/java.compiler/share/classes/javax/lang/model/util/package-info.java line 114:

> 112:  * Given the {@code default} method on the visitor interface, the
> 113:  * preview visitor classes need to override this method and take an
> 114:  * appropriate action for the visitor's semantics:

Suggestion:

 * action appropriate for the visitor's semantics:

src/java.compiler/share/classes/javax/lang/model/util/package-info.java line 192:

> 190:  * methods operating over the feature pulled in from the preview
> 191:  * visitors. Each preview visitor would then have its direct
> 192:  * superclass changed to the new corresponding (<i>N+k</i>) visitor.

"Added with" sounds weird, consider rephrasing:

Suggestion:

 * When preview feature 1 exits preview in JDK (<i>N+k</i>), the
 * methods operating over the feature pulled in from the preview
 * visitors, would be added to a set of visitors for language level
 * (<i>N+k</i>). Each preview visitor would then have its direct
 * superclass changed to the new corresponding (<i>N+k</i>) visitor.

src/java.compiler/share/classes/javax/lang/model/util/package-info.java line 291:

> 289:  * As in the case where a new interface is introduced, when preview
> 290:  * feature 2 exits preview in JDK (<i>N+k</i>), a set of visitors for
> 291:  * language level (<i>N+k</i>) would be added with the methods

Ditto for "added with".

-------------

PR Review: https://git.openjdk.org/jdk/pull/18804#pullrequestreview-2005553569
PR Review Comment: https://git.openjdk.org/jdk/pull/18804#discussion_r1568547989
PR Review Comment: https://git.openjdk.org/jdk/pull/18804#discussion_r1568557360
PR Review Comment: https://git.openjdk.org/jdk/pull/18804#discussion_r1568564158
PR Review Comment: https://git.openjdk.org/jdk/pull/18804#discussion_r1568607957
PR Review Comment: https://git.openjdk.org/jdk/pull/18804#discussion_r1568619649