Painless: Improve Documentation

[jdconrad]

Painless documentation plan --

Quick Start - Use existing documentation to create quick start guide
Lang Spec - General lang spec for Painless
Examples - Show code for Painless
Bindings - Explain each available variable for the binding (context)

• Quick Start: Guide
• Lang Spec: Intro (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Comments (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Keywords (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Literals (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Identifiers (Painless: Docs Clean Up #29592)
• Lang Spec: Variables (Painless: Docs Clean Up #29592)
• Lang Spec: Types (Painless: Types Section Clean Up #30283)
• Lang Spec: Casting (Painless: Types Section Clean Up #30283)
• Lang Spec: Operators (Painless: Restructure Spec Documentation #31013)
• Lang Spec: Statements
• Lang Spec: Scripts
• Lang Spec: Functions
• Lang Spec: Lambdas
• Lang Spec: Regex
• Examples: General
• Examples: Dates
• Contexts: API (Painless: Add Context Docs #31190)
• Contexts: Fields
• Contexts: Examples (in progress) (Painless: Add an Ingest Script Processor Example #32302) (Painless: Add reindex docs example #34024) ([Painless] Context Doc Examples #34829) (jdconrad)
• Other: Debugging
• Other: Execution

[jdconrad]

Wanted to give an update on this: @debadair has done some significant editing on the intro and constants, variables, and types sections. And she's come up with this as a possible model for the re-vamped documentation moving forward:

    Painless Scripting

    <introduction>

        Getting Started with Painless

            Accessing Doc Values 

            Updating Fields

            Working with Dates

            Using Regular Expressions

            Debugging Painless Scripts

    Example Scripts

        Using Painless in Script Fields

        Using Painless in Watches

        Using Painless in Function Score Queries

        Using Painless in Script Queries

        Using Painless When Updating Docs

        Using Painless When Reindexing

    How Painless Works

        Painless Architecture

        Dispatching Functions

    Painless Language Specification

    Painless API Reference

I am about 3/4 of the way through the operators section and plan to be done this week after which I'll hand it off for editing and move onto Control Flow.

I'm thinking that we an edit what already exists into the quick start guide and possibly post the lang spec with the initial 5 sections -- intro, constants variables and types, operators, control flow, and structure. This will help get some better docs out sooner, and then move forward from there.

[jdconrad]

Added the working progress to a branch here: https://github.com/jdconrad/elasticsearch/blob/painless-docs/docs/reference/modules/scripting/painless-lang-spec.asciidoc\

Important: This does not contain the editing that Deb has done yet! It's very raw still.

[clintongormley]

See https://www.elastic.co/guide/en/elasticsearch/painless/current/index.html for this work in progress

[jdconrad]

Update: No real progress as script contexts have taken priority. @talevy has kindly volunteered to help with some of the script context example documentation when he has a bit of time.

[jdconrad]

Update: Currently working on re-structuring and cleaning up some of the existing documentation. Control flow documentation soon to follow.

[jdconrad]

PR to rework the structure and clean up comments, keywords, and literals. (#29441)

[jdconrad]

PR to add identifiers and improve existing docs for variables. (#29592)

[jdconrad]

PR for types clean up in the spec. (#30283)

[jdconrad]

PR for casting clean up in the spec. (#30283)

[jdconrad]

PR for operator restructure plus some clean up (#31013).

[jdconrad]

Notes following clean up:

1. Add documentation for how byte, short, and char literals are implicitly cast the appropriate type if within a valid range.
2. Should all examples include promotion?
3. Should all examples use promotion only for run-time? This is kind of already the case.
4. Consider 'use' instead of 'uses' in example descriptions.
5. Should integral' be used instead of 'integer?'
6. Should reference definitions be added for list/map since they are used heavily in examples?
7. Do errors sections need more consistency?
8. Consider simplifying syntax for implicit cast in examples.
9. Consider use of 'expression' versus 'value'; 'value' is likely the best description given the current definitions.
10. Operators sections probably could use more links to types and casting.
11. Ensure consistency of semicolons in callouts.
12. Ensure consistency of 'evaluted value' versus just 'value.'

[jdconrad]

Current branches for changes:

1. docs6 -> numeric operators (https://github.com/jdconrad/elasticsearch/blob/docs6/docs/painless/painless-operators-numeric.asciidoc)
2. docs7 -> reference operators (https://github.com/jdconrad/elasticsearch/blob/docs7/docs/painless/painless-operators-general.asciidoc)
3. docs8 -> array operators (https://github.com/jdconrad/elasticsearch/blob/docs8/docs/painless/painless-operators-array.asciidoc)
4. docs9 -> boolean operators (https://github.com/jdconrad/elasticsearch/blob/docs9/docs/painless/painless-operators-boolean.asciidoc)

I will turn each of these into a PR as each prior PR is committed.

[jdconrad]

Note - is type value too verbose? Consider changing X type value to X type, X value, X variable, and X field where X is the specific type such as reference, numeric, int, String, etc.

[jdconrad]

PR for operator restructure/clean up is committed (#31013) to both 7 and 6.4.

[jdconrad]

PR for context information (#31190).

[jdconrad]

Context information has been committed.

[jdconrad]

Begun to add context examples (#32302).

[jrodewig]

[docs issue triage]

[stu-elastic]

Context documentation migrated to #49865

[jdconrad]

Closing in favor of newer issues.