From c6e2312fef5b3c4d40ccb887a07093747fb5b25e Mon Sep 17 00:00:00 2001 From: Joe Darcy Date: Fri, 6 Sep 2024 14:47:31 -0700 Subject: [PATCH 1/4] JDK-8339696: Clarify modeling scope of javax.lang.model.element --- .../javax/lang/model/element/package-info.java | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java index 4bb7444cb394f..ce33354b09509 100644 --- a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java +++ b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2024, 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 @@ -32,9 +32,15 @@ * The interfaces in this package do not model the structure of a * program inside a method body; for example there is no * representation of a {@code for} loop or {@code try}-{@code finally} - * block. However, the interfaces can model some structures only - * appearing inside method bodies, such as local variables and - * anonymous classes. + * block. Concretely, there is no model of the abstract syntax tree + * (AST) structure of a Java program. + * However, the interfaces can model some structures only + * appearing inside method bodies, such as {@linkplain ElementKind#LOCAL_VARIABLE local variables}, + * {@linkplain NestingKind#ANONYMOUS anonymous classes}, and + * {@linkplain ElementKind#EXCEPTION_PARAMETER exception parameters}. + * Therefore, these interfaces can be used by an AST API to model the + * declarations found in the method bodies of Java compilation units + * (JLS {@jls 7.3}). * *

When used in the context of annotation * processing, an accurate model of the element being represented must From 2c213737c92043e5eab9786404cb543c93ba1929 Mon Sep 17 00:00:00 2001 From: Joe Darcy Date: Fri, 6 Sep 2024 15:33:27 -0700 Subject: [PATCH 2/4] Appease jcheck. --- .../share/classes/javax/lang/model/element/package-info.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java index ce33354b09509..76f1242f05551 100644 --- a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java +++ b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java @@ -37,7 +37,7 @@ * However, the interfaces can model some structures only * appearing inside method bodies, such as {@linkplain ElementKind#LOCAL_VARIABLE local variables}, * {@linkplain NestingKind#ANONYMOUS anonymous classes}, and - * {@linkplain ElementKind#EXCEPTION_PARAMETER exception parameters}. + * {@linkplain ElementKind#EXCEPTION_PARAMETER exception parameters}. * Therefore, these interfaces can be used by an AST API to model the * declarations found in the method bodies of Java compilation units * (JLS {@jls 7.3}). From ac8ac99568444e3d82f6d160c23cd87d4ee8a939 Mon Sep 17 00:00:00 2001 From: Joe Darcy Date: Mon, 9 Sep 2024 08:05:38 -0700 Subject: [PATCH 3/4] Reflow paragraph. --- .../classes/javax/lang/model/element/package-info.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java index 76f1242f05551..4600ed87c09e6 100644 --- a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java +++ b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java @@ -33,9 +33,9 @@ * program inside a method body; for example there is no * representation of a {@code for} loop or {@code try}-{@code finally} * block. Concretely, there is no model of the abstract syntax tree - * (AST) structure of a Java program. - * However, the interfaces can model some structures only - * appearing inside method bodies, such as {@linkplain ElementKind#LOCAL_VARIABLE local variables}, + * (AST) structure of a Java program. However, the interfaces can + * model some structures only appearing inside method bodies, such as + * {@linkplain ElementKind#LOCAL_VARIABLE local variables}, * {@linkplain NestingKind#ANONYMOUS anonymous classes}, and * {@linkplain ElementKind#EXCEPTION_PARAMETER exception parameters}. * Therefore, these interfaces can be used by an AST API to model the From 53c187db1c6e1d43d30f95c3832983c9fd13307d Mon Sep 17 00:00:00 2001 From: Joe Darcy Date: Mon, 9 Sep 2024 12:15:44 -0700 Subject: [PATCH 4/4] Implement review feedbacck. --- .../share/classes/javax/lang/model/element/package-info.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java index 4600ed87c09e6..56edb89d3e35c 100644 --- a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java +++ b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java @@ -32,7 +32,7 @@ * The interfaces in this package do not model the structure of a * program inside a method body; for example there is no * representation of a {@code for} loop or {@code try}-{@code finally} - * block. Concretely, there is no model of the abstract syntax tree + * block. Concretely, there is no model of any abstract syntax tree * (AST) structure of a Java program. However, the interfaces can * model some structures only appearing inside method bodies, such as * {@linkplain ElementKind#LOCAL_VARIABLE local variables},