Improve painless docs for score, similarity, weight and sort (#35629)

docs/painless/painless-contexts/painless-score-context.asciidoc

@@ -11,8 +11,10 @@ score to documents returned from a query.
         User-defined parameters passed in as part of the query.
 
 `doc` (`Map`, read-only)::
-        Contains the fields of the current document where each field is a
-        `List` of values.
+        Contains the fields of the current document.  For single-valued fields,
+        the value can be accessed via `doc['fieldname'].value`.  For multi-valued
+        fields, this returns the first value; other values can be accessed
+        via `doc['fieldname'].get(index)`
 
 `_score` (`double` read-only)::
         The similarity score of the current document.
@@ -24,4 +26,33 @@ score to documents returned from a query.
 
 *API*
 
-The standard <<painless-api-reference, Painless API>> is available.
+The standard <<painless-api-reference, Painless API>> is available.
+
+*Example*
+
+To run this example, first follow the steps in
+<<painless-context-examples, context examples>>.
+
+The following query finds all unsold seats, with lower 'row' values
+scored higher.
+
+[source,js]
+--------------------------------------------------
+GET /seats/_search
+{
+    "query": {
+        "function_score": {
+            "query": {
+                "match": { "sold": "false" }
+            },
+            "script_score" : {
+                "script" : {
+                  "source": "1.0 / doc['row'].value"
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:seats]

docs/painless/painless-contexts/painless-similarity-context.asciidoc

@@ -15,6 +15,9 @@ documents in a query.
 `params` (`Map`, read-only)::
         User-defined parameters passed in at query-time.
 
+`weight` (`float`, read-only)::
+        The weight as calculated by a {ref}/painless-weight-context[weight script]
+
 `query.boost` (`float`, read-only)::
         The boost value if provided by the query.  If this is not provided the
         value is `1.0f`.
@@ -37,12 +40,23 @@ documents in a query.
         The total occurrences of the current term in the index.
 
 `doc.length` (`long`, read-only)::
-        The number of tokens the current document has in the current field.
+        The number of tokens the current document has in the current field.  This
+        is decoded from the stored {ref}/norms[norms] and may be approximate for
+        long fields
 
 `doc.freq` (`long`, read-only)::
         The number of occurrences of the current term in the current
         document for the current field.
 
+Note that the `query`, `field`, and `term` variables are also available to the
+{ref}/painless-weight-context[weight context]. They are more efficiently used
+there, as they are constant for all documents.
+
+For queries that contain multiple terms, the script is called once for each
+term with that term's calculated weight, and the results are summed.  Note that some
+terms might have a `doc.freq` value of `0` on a document, for example if a query
+uses synonyms.
+
 *Return*
 
 `double`::

docs/painless/painless-contexts/painless-sort-context.asciidoc

@@ -10,8 +10,10 @@ Use a Painless script to
         User-defined parameters passed in as part of the query.
 
 `doc` (`Map`, read-only)::
-        Contains the fields of the current document where each field is a
-        `List` of values.
+        Contains the fields of the current document.  For single-valued fields,
+        the value can be accessed via `doc['fieldname'].value`.  For multi-valued
+        fields, this returns the first value; other values can be accessed
+        via `doc['fieldname'].get(index)`
 
 `_score` (`double` read-only)::
         The similarity score of the current document.
@@ -23,4 +25,37 @@ Use a Painless script to
 
 *API*
 
-The standard <<painless-api-reference, Painless API>> is available.
+The standard <<painless-api-reference, Painless API>> is available.
+
+*Example*
+
+To run this example, first follow the steps in
+<<painless-context-examples, context examples>>.
+
+To sort results by the length of the `theatre` field, submit the following query:
+
+[source,js]
+----
+GET /_search
+{
+    "query" : {
+        "term" : { "sold" : "true" }
+    },
+    "sort" : {
+        "_script" : {
+            "type" : "number",
+            "script" : {
+                "lang": "painless",
+                "source": "doc['theatre'].value.length() * params.factor",
+                "params" : {
+                    "factor" : 1.1
+                }
+            },
+            "order" : "asc"
+        }
+    }
+}
+
+----
+// CONSOLE
+// TEST[setup:seats]

docs/painless/painless-contexts/painless-weight-context.asciidoc

@@ -3,8 +3,11 @@
 
 Use a Painless script to create a
 {ref}/index-modules-similarity.html[weight] for use in a
-<<painless-similarity-context, similarity script>>.  Weight is used to prevent
-recalculation of constants that remain the same across documents.
+<<painless-similarity-context, similarity script>>.  The weight makes up the
+part of the similarity calculation that is independent of the document being
+scored, and so can be built up front and cached.
+
+Queries that contain multiple terms calculate a separate weight for each term.
 
 *Variables*