Painless: Docs Clean Up (#29592)

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

Author: jdconrad

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.