We state that painless is similar than Groovy, but to be fair most of the code that you paste from groovy will need to be modified in order to work with this new language.

One simple example is the following that works in Groovy but not in Painless:

variable = list.sort { a, b -> a.value == b.value ? 0 : a.value < b.value ? -1 : 1 }

Now, this could be translated into the following:

variable = list.sort( (a, b) -> a.value == b.value ? 0 : a.value < b.value ? -1 : 1 );

Also, looks like joda.time.DateTime cannot be used, and there is no clear explanation how to deal with dates. See #22162.

As you can see, it's similar, but still you usually need to modify a big part of the code. Unfortunately this type of similarities are not documented, nor you can understand in an easy way how to translate groovy or how to develop with painless. My proposal is to:

1. Clearly explain in the documentation that while it's similar to groovy, there are a lot of differences which means that you will need to translate most of your code into painless.
2. Enhance the documentation with sections like "how to translate groovy to painless".
3. Add more sample docs around painless.
4. Add documentation on how the language works, what things we support, and what things we don't support.

We shouldn't expect to have a large documentation, but at least to have the general concepts. Just to see how other languages are explained:

• C#: https://msdn.microsoft.com/en-us/library/67ef8sbd.aspx
• Java: https://docs.oracle.com/javase/specs/jls/se8/html/index.html
• Groovy http://groovy-lang.org/documentation.html (note the "differences with Java section")