SQL: Document a few functions (elastic/x-pack-elasticsearch#3390)

* Starts to build the list of supported functions, adding links to
wikipedia when there is any doubt what the functions mean.
* Extracts an example of using the function from the test suite.
* Explicitly calls out how we round (half up) because there are
lots of ways to round.

Original commit: elastic/x-pack-elasticsearch@5fb64ba869

docs/en/sql/functions/sql-functions.asciidoc

@@ -1,11 +1,257 @@
 [[sql-functions]]
 == Functions and Operators
 
+=== Comparison Operators
+
+Elasticsearch SQL supports the following comparison operators:
+
+* Equality (`=`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereFieldEquality]
+--------------------------------------------------
+
+* Inequality (`<>` or `!=`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereFieldNonEquality]
+--------------------------------------------------
+
+* Comparison (`<`, `<=`, `>`, `>=`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereFieldLessThan]
+--------------------------------------------------
+
+* `BETWEEN`
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereBetween]
+--------------------------------------------------
+
+* `IS NULL`/`IS NOT NULL`
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereIsNotNullAndIsNull]
+--------------------------------------------------
+
+
+=== Logical Operators
+
+Elasticsearch SQL supports the following logical operators:
+
+* `AND`
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereFieldAndComparison]
+--------------------------------------------------
+
+* `OR`
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereFieldOrComparison]
+--------------------------------------------------
+
+* `NOT`
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/filter.sql-spec[whereFieldEqualityNot]
+--------------------------------------------------
+
+
+=== Math Operators
+
+Elasticsearch SQL supports the following math operators:
+
+* Add (`+`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/arithmetic.sql-spec[plus]
+--------------------------------------------------
+
+* Subtract (infix `-`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/arithmetic.sql-spec[minus]
+--------------------------------------------------
+
+* Negate (unary `-`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/arithmetic.sql-spec[unaryMinus]
+--------------------------------------------------
+
+* Multiply (`*`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/arithmetic.sql-spec[multiply]
+--------------------------------------------------
+
+* Divide (`/`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/arithmetic.sql-spec[divide]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Modulo_operation[Modulo] (`%`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/arithmetic.sql-spec[mod]
+--------------------------------------------------
+
+
+=== Math Functions
+==== Basic
+
+* https://en.wikipedia.org/wiki/Absolute_value[Absolute value] (`ABS`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[abs]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Rounding#Round_half_up[Round] (`ROUND`)
+
+TODO make the example in the tests presentable
+
+NOTE: This rounds "half up" meaning that `ROUND(-1.5)` results in `-1`.
+
+* https://en.wikipedia.org/wiki/Floor_and_ceiling_functions[Ceiling] (`CEIL`)
+
+TODO make the example in the tests presentable
+
+* https://en.wikipedia.org/wiki/Floor_and_ceiling_functions[Floor] (`FLOOR`)
+
+TODO make the example in the tests presentable
+
+* https://en.wikipedia.org/wiki/Natural_logarithm[Natural logarithm] (`LOG`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[log]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Logarithm[Logarithm] base 10 (`LOG10`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[log10]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Square_root[Square root] (`SQRT`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[sqrt]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Cube_root[Cube root] (`CBRT`)
+
+TODO make the example in the tests presentable
+
+* https://en.wikipedia.org/wiki/Exponential_function[e^x^] (`EXP`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[exp]
+--------------------------------------------------
+
+* https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#expm1-double-[e^x^ - 1] (`EXPM1`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[expm1]
+--------------------------------------------------
+
+==== Trigonometric
+
+* Convert from https://en.wikipedia.org/wiki/Radian[radians]
+to https://en.wikipedia.org/wiki/Degree_(angle)[degrees] (`DEGREES`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[degrees]
+--------------------------------------------------
+
+* Convert from https://en.wikipedia.org/wiki/Degree_(angle)[degrees]
+to https://en.wikipedia.org/wiki/Radian[radians] (`RADIANS`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[degrees]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Trigonometric_functions#sine[Sine] (`SIN`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[sin]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Trigonometric_functions#cosine[Cosine] (`COS`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[cos]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Trigonometric_functions#tangent[Tangent] (`TAN`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[tan]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[Arc sine] (`ASIN`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[asin]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[Arc cosine] (`ACOS`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[acos]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[Arc tangent] (`ATAN`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[atan]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Hyperbolic_function[Hyperbolic sine] (`SINH`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[sinh]
+--------------------------------------------------
+
+* https://en.wikipedia.org/wiki/Hyperbolic_function[Hyperbolic cosine] (`COSH`)
+
+["source","sql",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/math.sql-spec[cosh]
+--------------------------------------------------
 
-// logical operators
-// comparison
 // conversion
-// math
 // date time
 // aggregate
 

docs/en/sql/language/sql-syntax.asciidoc

@@ -7,7 +7,7 @@ Each entry might get its own file and code snippet
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{sql-spec}/select.sql-spec[wildcardWithOrder]
+include-tagged::{sql-specs}/select.sql-spec[wildcardWithOrder]
 --------------------------------------------------
 
 

qa/sql/src/main/resources/arithmetic.sql-spec

@@ -3,17 +3,29 @@
 //
 
 unaryMinus
+// tag::unaryMinus
 SELECT - 1 AS x;
+// end::unaryMinus
 plus
+// tag::plus
 SELECT 1 + 1 AS x;
+// end::plus
 minus
+// tag::minus
 SELECT 1 - 1 AS x;
+// end::minus
 divide
+// tag::divide
 SELECT 6 / 3 AS x;
+// end::divide
 multiply
+// tag::multiply
 SELECT 2 * 3 AS x;
+// end::multiply
 mod
+// tag::mod
 SELECT 5 % 2 AS x;
+// end::mod
 operatorsPriority
 SELECT 1 + 3 * 4 / 2 - 2 AS x;
 operatorsPriorityWithParanthesis

qa/sql/src/main/resources/filter.sql-spec

@@ -3,20 +3,33 @@
 //
 
 whereFieldEquality
+// tag::whereFieldEquality
 SELECT last_name l FROM "test_emp" WHERE emp_no = 10000 LIMIT 5;
+// end::whereFieldEquality
 whereFieldNonEquality
+// tag::whereFieldNonEquality
 SELECT last_name l FROM "test_emp" WHERE emp_no <> 10000 ORDER BY emp_no LIMIT 5;
+// end::whereFieldNonEquality
 whereFieldNonEqualityJavaSyntax
 SELECT last_name l FROM "test_emp" WHERE emp_no != 10000 ORDER BY emp_no LIMIT 5;
 whereFieldLessThan
+// tag::whereFieldLessThan
 SELECT last_name l FROM "test_emp" WHERE emp_no < 10003 ORDER BY emp_no LIMIT 5;
+// end::whereFieldLessThan
 whereFieldAndComparison
+// tag::whereFieldAndComparison
 SELECT last_name l FROM "test_emp" WHERE emp_no > 10000 AND emp_no < 10005 ORDER BY emp_no LIMIT 5;
+// end::whereFieldAndComparison
 whereFieldOrComparison
+// tag::whereFieldOrComparison
 SELECT last_name l FROM "test_emp" WHERE emp_no < 10003 OR emp_no = 10005 ORDER BY emp_no LIMIT 5;
+// end::whereFieldOrComparison
+
 
 whereFieldEqualityNot
+// tag::whereFieldEqualityNot
 SELECT last_name l FROM "test_emp" WHERE NOT emp_no = 10000 LIMIT 5;
+// end::whereFieldEqualityNot
 whereFieldNonEqualityNot
 SELECT last_name l FROM "test_emp" WHERE NOT emp_no <> 10000 ORDER BY emp_no LIMIT 5;
 whereFieldNonEqualityJavaSyntaxNot
@@ -56,8 +69,12 @@ SELECT last_name l FROM "test_emp" WHERE emp_no IS NOT NULL AND emp_no < 10005 O
 whereIsNull
 SELECT last_name l FROM "test_emp" WHERE emp_no IS NULL;
 whereIsNotNullAndIsNull
+// tag::whereIsNotNullAndIsNull
 SELECT last_name l FROM "test_emp" WHERE emp_no IS NOT NULL AND gender IS NULL;
+// end::whereIsNotNullAndIsNull
 whereBetween
+// tag::whereBetween
 SELECT last_name l FROM "test_emp" WHERE emp_no BETWEEN 9990 AND 10003 ORDER BY emp_no;
+// end::whereBetween
 whereNotBetween
 SELECT last_name l FROM "test_emp" WHERE emp_no NOT BETWEEN 10010 AND 10020 ORDER BY emp_no LIMIT 5;

qa/sql/src/main/resources/math.sql-spec

@@ -3,42 +3,78 @@
 //
 
 mathAbs
+// tag::abs
 SELECT ABS(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::abs
 mathACos
+// tag::acos
 SELECT ACOS(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::acos
 mathASin
+// tag::asin
 SELECT ASIN(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::asin
 mathATan
+// tag::atan
 SELECT ATAN(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::atan
 //mathCbrt
 //SELECT CBRT(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
 mathCeil
 // H2 returns CEIL as a double despite the value being an integer; we return a long as the other DBs
 SELECT CAST(CEIL(emp_no) AS INT) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
 mathCos
+// tag::cos
 SELECT COS(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::cos
 mathCosh
+// tag::cosh
 SELECT COSH(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::cosh
 mathDegrees
+// tag::degrees
 SELECT DEGREES(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::degrees
+mathExp
+// tag::exp
+SELECT EXP(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::exp
+mathExpm1
+// tag::expm1
+SELECT EXP(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::expm1
 mathFloor
 SELECT CAST(FLOOR(emp_no) AS INT) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
 mathLog
+// tag::log
 SELECT LOG(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::log
 mathLog10
+// tag::log10
 SELECT LOG10(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::log10
 mathRadians
+// tag::radians
 SELECT RADIANS(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::radians
 mathRound
 SELECT CAST(ROUND(emp_no) AS INT) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
 mathSin
+// tag::sin
 SELECT SIN(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::sin
 mathSinH
+// tag::sinh
 SELECT SINH(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::sinh
 mathSqrt
+// tag::sqrt
 SELECT SQRT(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::sqrt
 mathTan
+// tag::tan
 SELECT TAN(emp_no) m, first_name FROM "test_emp" WHERE emp_no < 10010 ORDER BY emp_no;
+// end::tan
 
 //
 // Combined methods

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/arithmetic/Add.java

@@ -9,6 +9,9 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.arithmetic.BinaryArithmeticProcessor.BinaryArithmeticOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * Addition function ({@code a + b}).
+ */
 public class Add extends ArithmeticFunction {
 
     public Add(Location location, Expression left, Expression right) {

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/arithmetic/Div.java

@@ -11,6 +11,9 @@ import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.type.DataType;
 import org.elasticsearch.xpack.sql.type.DataTypeConversion;
 
+/**
+ * Division function ({@code a / b}).
+ */
 public class Div extends ArithmeticFunction {
 
     public Div(Location location, Expression left, Expression right) {

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/arithmetic/Mod.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.arithmetic.BinaryArithmeticProcessor.BinaryArithmeticOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Modulo_operation">Modulo</a>
+ * function ({@code a % b}).
+ */
 public class Mod extends ArithmeticFunction {
 
     public Mod(Location location, Expression left, Expression right) {

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/arithmetic/Mul.java

@@ -9,6 +9,9 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.arithmetic.BinaryArithmeticProcessor.BinaryArithmeticOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * Multiplication function ({@code a * b}).
+ */
 public class Mul extends ArithmeticFunction {
 
     public Mul(Location location, Expression left, Expression right) {

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/arithmetic/Neg.java

@@ -15,6 +15,9 @@ import org.elasticsearch.xpack.sql.expression.function.scalar.processor.definiti
 import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.type.DataType;
 
+/**
+ * Negation function (@{code -x}).
+ */
 public class Neg extends UnaryScalarFunction {
 
     public Neg(Location location, Expression field) {

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/arithmetic/Sub.java

@@ -9,6 +9,9 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.arithmetic.BinaryArithmeticProcessor.BinaryArithmeticOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * Subtraction function ({@code a - b}).
+ */
 public class Sub extends ArithmeticFunction {
 
     public Sub(Location location, Expression left, Expression right) {

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/ACos.java

@@ -9,6 +9,11 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+
+/**
+ * <a href="https://en.wikipedia.org/wiki/Inverse_trigonometric_functions">Arc cosine</a>
+ * fuction.
+ */
 public class ACos extends MathFunction {
     public ACos(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/ASin.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Inverse_trigonometric_functions">Arc sine</a>
+ * fuction.
+ */
 public class ASin extends MathFunction {
     public ASin(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/ATan.java

@@ -9,6 +9,11 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+
+/**
+ * <a href="https://en.wikipedia.org/wiki/Inverse_trigonometric_functions">Arc tangent</a>
+ * fuction.
+ */
 public class ATan extends MathFunction {
     public ATan(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Abs.java

@@ -10,6 +10,10 @@ import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor
 import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.type.DataType;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Absolute_value">Absolute value</a>
+ * function.
+ */
 public class Abs extends MathFunction {
     public Abs(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Cbrt.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Cube_root">Cube root</a>
+ * function.
+ */
 public class Cbrt extends MathFunction {
     public Cbrt(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Ceil.java

@@ -11,6 +11,10 @@ import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.type.DataType;
 import org.elasticsearch.xpack.sql.type.DataTypeConversion;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Floor_and_ceiling_functions">Ceiling</a>
+ * function.
+ */
 public class Ceil extends MathFunction {
     public Ceil(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Cos.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Trigonometric_functions#cosine">Cosine</a>
+ * function.
+ */
 public class Cos extends MathFunction {
     public Cos(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Cosh.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Hyperbolic_function">Hyperbolic cosine</a>
+ * function.
+ */
 public class Cosh extends MathFunction {
     public Cosh(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Degrees.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * Convert from <a href="https://en.wikipedia.org/wiki/Radian">radians</a>
+ * to <a href="https://en.wikipedia.org/wiki/Degree_(angle)">degrees</a>.
+ */
 public class Degrees extends MathFunction {
     public Degrees(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Exp.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Exponential_function">e<sup>x</sup></a>
+ * function.
+ */
 public class Exp extends MathFunction {
     public Exp(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Expm1.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#expm1-double-">e<sup>x</sup> + 1</a>
+ * function.
+ */
 public class Expm1 extends MathFunction {
     public Expm1(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Floor.java

@@ -11,6 +11,10 @@ import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.type.DataType;
 import org.elasticsearch.xpack.sql.type.DataTypeConversion;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Floor_and_ceiling_functions">Floor</a>
+ * function.
+ */
 public class Floor extends MathFunction {
     public Floor(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Log.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Natural_logarithm">Natural logarithm</a>
+ * function.
+ */
 public class Log extends MathFunction {
     public Log(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Log10.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Logarithm">Logarithm</a>
+ * base 10 function.
+ */
 public class Log10 extends MathFunction {
     public Log10(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Radians.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * Convert from <a href="https://en.wikipedia.org/wiki/Degree_(angle)">degrees</a>
+ * to <a href="https://en.wikipedia.org/wiki/Radian">radians</a>.
+ */
 public class Radians extends MathFunction {
     public Radians(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Round.java

@@ -11,6 +11,13 @@ import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.type.DataType;
 import org.elasticsearch.xpack.sql.type.DataTypeConversion;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Rounding#Round_half_up">Round</a>
+ * function.
+ *
+ * Note that this uses {@link Math#round(double)} which uses "half up" rounding
+ * for `ROUND(-1.5)` rounds to `-1`.
+ */
 public class Round extends MathFunction {
     public Round(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Sin.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Trigonometric_functions#sine">Sine</a>
+ * fuction.
+ */
 public class Sin extends MathFunction {
     public Sin(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Sinh.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Hyperbolic_function">Hyperbolic sine</a>
+ * function.
+ */
 public class Sinh extends MathFunction {
     public Sinh(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Sqrt.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Square_root">Square root</a>
+ * function.
+ */
 public class Sqrt extends MathFunction {
     public Sqrt(Location location, Expression field) {
         super(location, field);

sql/server/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/math/Tan.java

@@ -9,6 +9,10 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.expression.function.scalar.math.MathProcessor.MathOperation;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * <a href="https://en.wikipedia.org/wiki/Trigonometric_functions#sine">Tangent</a>
+ * fuction.
+ */
 public class Tan extends MathFunction {
     public Tan(Location location, Expression field) {
         super(location, field);