Painless: Docs Clean Up (#29592)

As part of the lang spec: separated identifiers into its own section, and cleaned up variables section.

docs/painless/painless-comments.asciidoc

@@ -1,12 +1,12 @@
 [[painless-comments]]
 === Comments
 
-Painless supports both single-line and multi-line comments. Comments can be
-included anywhere within a script. Use the `//` token anywhere on a line to
-specify a single-line comment. All characters from the `//` token to the end
-of the line are ignored. Use an opening `/*` token and a closing `*/` token
-to specify a multi-line comment. Multi-line comments can start anywhere on a
-line, and all characters in between the `/*` token and `*/` token are ignored.
+Use the `//` token anywhere on a line to specify a single-line comment. All
+characters from the `//` token to the end of the line are ignored. Use an
+opening `/*` token and a closing `*/` token to specify a multi-line comment.
+Multi-line comments can start anywhere on a line, and all characters in between
+the `/*` token and `*/` token are ignored. Comments can be included anywhere
+within a script.
 
 *Grammar*
 [source,ANTLR4]
@@ -17,17 +17,17 @@ MULTI_LINE_COMMENT: '/*' .*? '*/';
 
 *Examples*
 
-Single-line comments.
-
+* Single-line comments.
++
 [source,Painless]
 ----
 // single-line comment
 
 int value; // single-line comment
 ----
-
-Multi-line comments.
-
++
+* Multi-line comments.
++
 [source,Painless]
 ----
 /* multi-

docs/painless/painless-identifiers.asciidoc

@@ -0,0 +1,29 @@
+[[painless-identifiers]]
+=== Identifiers
+
+Specify identifiers to <<declaration, declare>>, <<assignment, assign>>, and
+<<painless-operators, use>> variables, <<dot-operator, access fields>>, and
+<<dot-operator, call methods>>. <<painless-keywords, Keywords>> and
+<<painless-types, types>> cannot be used as identifiers.
+
+*Grammar*
+[source,ANTLR4]
+----
+ID: [_a-zA-Z] [_a-zA-Z-0-9]*;
+----
+
+*Examples*
+
+* Variations of identifiers.
++
+[source,Painless]
+----
+a
+Z
+id
+list
+list0
+MAP25
+_map25
+Map_25
+----

docs/painless/painless-keywords.asciidoc

@@ -2,8 +2,8 @@
 === Keywords
 
 The keywords in the table below are reserved for built-in language
-features. These keywords cannot be used as <<identifiers, identifiers>> or
-<<painless-types, types>>.
+features. These keywords cannot be used as
+<<painless-identifiers, identifiers>> or <<painless-types, types>>.
 
 [cols="^1,^1,^1,^1,^1"]
 |====

docs/painless/painless-lang-spec.asciidoc

@@ -23,6 +23,8 @@ include::painless-keywords.asciidoc[]
 
 include::painless-literals.asciidoc[]
 
+include::painless-identifiers.asciidoc[]
+
 include::painless-variables.asciidoc[]
 
 include::painless-types.asciidoc[]

docs/painless/painless-literals.asciidoc

@@ -24,18 +24,18 @@ HEX:     '-'? '0' [xX] [0-9a-fA-F]+ [lL]?;
 
 *Examples*
 
-Integer literals.
-
+* Integer literals.
++
 [source,Painless]
 ----
-0     <1>
-0D    <2>
-1234L <3>
--90f  <4>
--022  <5>
-0xF2A <6>
+<1> 0
+<2> 0D
+<3> 1234L
+<4> -90f
+<5> -022
+<6> 0xF2A
 ----
-
++
 <1> `int 0`
 <2> `double 0.0`
 <3> `long 1234`
@@ -61,17 +61,17 @@ EXPONENT: ( [eE] [+\-]? [0-9]+ );
 
 *Examples*
 
-Floating point literals.
-
+* Floating point literals.
++
 [source,Painless]
 ----
-0.0      <1>
-1E6      <2>
-0.977777 <3>
--126.34  <4>
-89.9F    <5>
+<1> 0.0
+<2> 1E6
+<3> 0.977777
+<4> -126.34
+<5> 89.9F
 ----
-
++
 <1> `double 0.0`
 <2> `double 1000000.0` in exponent notation
 <3> `double 0.977777`
@@ -81,12 +81,11 @@ Floating point literals.
 [[strings]]
 ==== Strings
 
-Use string literals to specify string values of the
-<<string-type, String type>> with either single-quotes or double-quotes.
-Use a `\"` token to include a double-quote as part of a double-quoted string
-literal. Use a `\'` token to include a single-quote as part of a single-quoted
-string literal.  Use a `\\` token to include a backslash as part of any string
-literal.
+Use string literals to specify <<string-type, String>> values with
+either single-quotes or double-quotes. Use a `\"` token to include a
+double-quote as part of a double-quoted string literal. Use a `\'` token to
+include a single-quote as part of a single-quoted string literal.  Use a `\\`
+token to include a backslash as part of any string literal.
 
 *Grammar*
 [source,ANTLR4]
@@ -97,22 +96,22 @@ STRING: ( '"'  ( '\\"'  | '\\\\' | ~[\\"] )*? '"'  )
 
 *Examples*
 
-String literals using single-quotes.
-
+* String literals using single-quotes.
++
 [source,Painless]
 ----
 'single-quoted string literal'
-'\'single-quoted string with escaped single-quotes\' and backslash \\'
-'single-quoted string with non-escaped "double-quotes"'
+'\'single-quoted with escaped single-quotes\' and backslash \\'
+'single-quoted with non-escaped "double-quotes"'
 ----
-
-String literals using double-quotes.
-
++
+* String literals using double-quotes.
++
 [source,Painless]
 ----
 "double-quoted string literal"
-"\"double-quoted string with escaped double-quotes\" and backslash: \\"
-"double-quoted string with non-escaped 'single-quotes'"
+"\"double-quoted with escaped double-quotes\" and backslash: \\"
+"double-quoted with non-escaped 'single-quotes'"
 ----
 
 [[characters]]
@@ -126,16 +125,16 @@ or an error will occur.
 
 *Examples*
 
-Casting string literals into <<primitive-types, char>> values.
-
+* Casting string literals into <<primitive-types, char>> values.
++
 [source,Painless]
 ----
 (char)"C"
 (char)'c'
 ----
-
-Casting a <<string-type, String>> value into a <<primitive-types, char>> value.
-
++
+* Casting a <<string-type, String>> value into a <<primitive-types, char>> value.
++
 [source,Painless]
 ----
 String s = "s";

docs/painless/painless-operators.asciidoc

@@ -704,6 +704,7 @@ e = ~d;      // sets e the negation of d
 
 The cast operator can be used to explicitly convert one type to another.  See casting [MARK] for more information.
 
+[[constructor-call]]
 ==== Constructor Call
 
 A constructor call is a special type of method call [MARK] used to allocate a reference type instance using the new operator.  The format is the new operator followed by a type, an opening parenthesis, arguments if any, and a closing parenthesis.  Arguments are a series of zero-to-many expressions delimited by commas.  Auto-boxing and auto-unboxing will be applied automatically for arguments passed into a constructor call.  See boxing and unboxing [MARK] for more information on this topic.  Constructor argument types can always be resolved at run-time; if appropriate type conversions (casting) cannot be applied an error will occur.  Once a reference type instance has been allocated, its members may be used as part of other expressions.

docs/painless/painless-variables.asciidoc

@@ -1,122 +1,130 @@
 [[painless-variables]]
 === Variables
 
-Variables in Painless must be declared and can be
-statically or <<dynamic-types, dynamically typed>>.
-
-[[identifiers]]
-==== Identifiers
-
-Specify variable identifiers using the following grammar. Variable identifiers
-must start with a letter or underscore. You cannot use
-<<painless-keywords, keywords>> or <<painless-types, types>> as identifiers.
-
-*Grammar:*
-[source,ANTLR4]
-----
-ID: [_a-zA-Z] [_a-zA-Z-0-9]*;
-----
-
-*Examples:*
-[source,Java]
-----
-a
-Z
-id
-list
-list0
-MAP25
-_map25
-----
+<<declaration, Declare>> variables to <<assignment, assign>> values for
+<<painless-operators, use>> in expressions.  Specify variables as a
+<<primitive-types, primitive type>>, <<reference-types, reference type>>, or
+<<dynamic-types, dynamic type>>.  Variable operations follow the structure of a
+standard JVM in relation to instruction execution and memory usage.
 
 [[declaration]]
 ==== Declaration
 
-Variables must be declared before you use them. The format is `type-name
-identifier-name`. To declare multiple variables of the same type, specify a
-comma-separated list of identifier names. You can immediately assign a value to
-a variable when you declare it.
+Declare variables before use with the format of <<painless-types, type>>
+<<painless-identifiers, identifier>>. Specify a comma-separated list of
+<<painless-identifiers, identifiers>> following the <<painless-types, type>>
+to declare multiple variables in a single statement.  Use an
+<<assignment, assignment>> statement combined with a declaration statement to
+immediately assign a value to a variable. Variables not immediately assigned a
+value will have a default value assigned implicitly based on the
+<<painless-types, type>>.
 
-*Grammar:*
+*Grammar*
 [source,ANTLR4]
 ----
+declaration : type ID assignment? (',' ID assignment?)*;
 type: ID ('[' ']')*;
-declaration : type ID (',' ID)*;
+assignment: '=' expression;
 ----
 
-*Examples:*
-[source,Java]
+*Examples*
+
+* Different variations of variable declaration.
++
+[source,Painless]
 ----
-int x;        // Declare a variable with type int and id x
-List y;       // Declare a variable with type List and id y
-int x, y, z;  // Declare variables with type int and ids x, y, and z
-def[] d;      // Declare the variable d with type def[]
-int i = 10;   // Declare the int variable i and set it to the int literal 10
+<1> int x;
+<2> List y;
+<3> int x, y, z;
+<4> def[] d;
+<5> int i = 10;
 ----
++
+<1> declare a variable of type `int` and identifier `x`
+<2> declare a variable of type `List` and identifier `y`
+<3> declare three variables of type `int` and identifiers `x`, `y`, `z`
+<4> declare a variable of type `def[]` and identifier `d`
+<5> declare a variable of type `int` and identifier `i`;
+    assign the integer literal `10` to `i`
 
-[[variable-assignment]]
+[[assignment]]
 ==== Assignment
 
-Use the equals operator (`=`) to assign a value to a variable. The format is
-`identifier-name = value`. Any value expression can be assigned to any variable
-as long as the types match or the expression's type can be implicitly cast to
-the variable's type. An error occurs if the types do not match.
+Use the `equals` operator (`=`) to assign a value to a variable. Any expression
+that produces a value can be assigned to any variable as long as the
+<<painless-types, types>> are the same or the resultant
+<<painless-types, type>> can be implicitly <<painless-casting, cast>> to
+the variable <<painless-types, type>>.  Otherwise, an error will occur.
+<<reference-types, Reference type>> values are shallow-copied when assigned.
 
-*Grammar:*
+*Grammar*
 [source,ANTLR4]
 ----
 assignment: ID '=' expression
 ----
 
-
-*Examples:*
-
-Assigning a literal of the appropriate type directly to a declared variable.
-
-[source,Java]
-----
-int i;   // Declare an int i
-i = 10;  // Set the int i to the int literal 10
-----
-
-Immediately assigning a value when declaring a variable.
-
-[source,Java]
-----
-int i = 10;     // Declare the int variable i and set it the int literal 1
-double j = 2.0; // Declare the double variable j and set it to the double
-                //   literal 2.0
-----
-
-Assigning a variable of one primitive type to another variable of the same
-type.
-
-[source,Java]
-----
-int i = 10; // Declare the int variable i and set it to the int literal 10
-int j = i;  // Declare the int variable j and set it to the int variable i
-----
-
-Assigning a reference type to a new heap allocation with the `new` operator.
-
-[source,Java]
-----
-ArrayList l = new ArrayList();  // Declare an ArrayList variable l and set it
-                                //   to a newly allocated ArrayList
-Map m = new HashMap();          // Declare a Map variable m and set it
-                                //   to a newly allocated HashMap
-----
-
-Assigning a variable of one reference type to another variable of the same type.
-
-[source,Java]
-----
-List l = new ArrayList(); // Declare List variable l and set it a newly
-                          //    allocated ArrayList
-List k = l;               // Declare List variable k and set it to the
-                          //    value of the List variable l
-List m;                   // Declare List variable m and set it the
-                          //    default value null
-m = k;                    // Set the value of List variable m to the value
-                          //    of List variable k
-----
+*Examples*
+
+* Variable assignment with an <<integers, integer literal>>.
++
+[source,Painless]
+----
+<1> int i;
+<2> i = 10;
+----
++
+<1> declare `int i`
+<2> assign `10` to `i`
++
+* <<declaration, Declaration>> combined with immediate variable assignment.
++
+[source,Painless]
+----
+<1> int i = 10;
+<2> double j = 2.0;
+----
++
+<1> declare `int i`; assign `10` to `i`
+<2> declare `double j`; assign `2.0` to `j`
++
+* Assignment of one variable to another using
+<<primitive-types, primitive types>>.
++
+[source,Painless]
+----
+<1> int i = 10;
+<2> int j = i;
+----
++
+<1> declare `int i`; assign `10` to `i`
+<2> declare `int j`; assign `j` to `i`
++
+* Assignment with <<reference-types, reference types>> using the
+<<constructor-call, new operator>>.
++
+[source,Painless]
+----
+<1> ArrayList l = new ArrayList();
+<2> Map m = new HashMap();
+----
++
+<1> declare `ArrayList l`; assign a newly-allocated `Arraylist` to `l`
+<2> declare `Map m`; assign a newly-allocated `HashMap` to `m`
+    with an implicit cast to `Map`
++
+* Assignment of one variable to another using
+<<reference-types, reference types>>.
++
+[source,Painless]
+----
+<1> List l = new ArrayList();
+<2> List k = l;
+<3> List m;
+<4> m = k;
+----
++
+<1> declare `List l`; assign a newly-allocated `Arraylist` to `l`
+    with an implicit cast to `List`
+<2> declare `List k`; assign a shallow-copy of `l` to `k`
+<3> declare `List m`;
+<4> assign a shallow-copy of `k` to `m`