Fix #42 - clarify meaning of scope of scripting variables for actions

api/src/main/java/jakarta/servlet/jsp/tagext/VariableInfo.java

@@ -61,6 +61,10 @@
  * <B>Synchronization Protocol</B>
  *
  * <p>
+ * The value of the `scope` attribute does not affect the visibility of the variables within the generated program. It
+ * affects where and thus for how long there will be additional references to the object denoted by the variable.
+ *
+ * <p>
  * The result of the invocation on getVariableInfo is an array of VariableInfo objects. Each such object describes a
  * scripting variable by providing its name, its type, whether the variable is new or not, and what its scope is. Scope
  * is best described through a picture:
@@ -72,12 +76,12 @@
  * The JSP 2.0 specification defines the interpretation of 3 values:
  * 
  * <ul>
- * <li>NESTED, if the scripting variable is available between the start tag and the end tag of the action that defines
- * it.
- * <li>AT_BEGIN, if the scripting variable is available from the start tag of the action that defines it until the end
- * of the scope.
- * <li>AT_END, if the scripting variable is available after the end tag of the action that defines it until the end of
- * the scope.
+ * <li>NESTED, if the scripting variable is synchronized with the calling page between the start tag and the end tag of
+ * the action that defines it.
+ * <li>AT_BEGIN, if the scripting variable is synchronized with the calling page from the start tag of the action that
+ * defines it until the end of the scope.
+ * <li>AT_END, if the scripting variable is synchronized with the calling page after the end tag of the action that
+ * defines it until the end of the scope.
  * </ul>
  *
  * The scope value for a variable implies what methods may affect its value and thus where synchronization is needed as
@@ -168,17 +172,17 @@
 public class VariableInfo {
 
     /**
-     * Scope information that scripting variable is visible only within the start/end tags.
+     * Scope information that scripting variable is synchronized with the calling page only within the start/end tags.
      */
     public static final int NESTED = 0;
 
     /**
-     * Scope information that scripting variable is visible after start tag.
+     * Scope information that scripting variable is synchronized with the calling page after start tag.
      */
     public static final int AT_BEGIN = 1;
 
     /**
-     * Scope information that scripting variable is visible after end tag.
+     * Scope information that scripting variable is synchronized with the calling page after end tag.
      */
     public static final int AT_END = 2;
 
@@ -188,7 +192,7 @@ public class VariableInfo {
      * @param varName   The name of the scripting variable
      * @param className The type of this variable
      * @param declare   If true, it is a new variable (in some languages this will require a declaration)
-     * @param scope     Indication on the lexical scope of the variable
+     * @param scope     Indication of the synchronization scope of the variable
      */
     public VariableInfo(String varName, String className, boolean declare, int scope) {
         this.varName = varName;
@@ -227,9 +231,9 @@ public boolean getDeclare() {
     }
 
     /**
-     * Returns the lexical scope of the variable.
+     * Returns the synchronization scope of the variable.
      * 
-     * @return the lexical scope of the variable, either AT_BEGIN, AT_END, or NESTED.
+     * @return the synchronization scope of the variable, either AT_BEGIN, AT_END, or NESTED.
      * @see #AT_BEGIN
      * @see #AT_END
      * @see #NESTED

spec/src/main/asciidoc/ServerPages.adoc

@@ -9955,7 +9955,7 @@ this corresponds to a statement of the form:
 
 An action defining one or more objects is
 transformed into one or more variable declarations for those objects,
-together with code that initializes the variables. Their visibility is
+together with code that initializes the variables. Their visibility may be
 affected by other constructs, for example scriptlets.
 
 The semantics of the action type determines
@@ -9983,10 +9983,14 @@ type is the type of the `class` attribute.
 
 |===
 
-Note that the value of the `scope` attribute
-does not affect the visibility of the variables within the generated
-program. It affects where and thus for how long there will be additional
-references to the object denoted by the variable.
+Note that as per <<Implementation Flexibility>>, implementations may opt to take
+a different approach to the location of variable declarations. The value of the
+`scope` attribute does not affect the visibility of the variables within the
+generated program. It affects where and thus for how long there will be
+additional references to the object denoted by the variable. Developers wishing
+to have more precise control over variable declarations may configure the
+variables with `declare=false` and explicitly declare the variables themselves.
+
 
 // Table, figure numbering etc
 :table-number: 0