From f18583c1ace9998c8d45bae09f80f51711041343 Mon Sep 17 00:00:00 2001
From: Steven Van Ingelgem <steven.vaningelgem@kbc.be>
Date: Fri, 13 Oct 2023 11:59:25 +0200
Subject: [PATCH] docs(rust): Improving the documentation of the SQL
 expressions (#11708)

---
 crates/polars-sql/src/functions.rs | 85 +++++++++++++++++++++++++-----
 1 file changed, 72 insertions(+), 13 deletions(-)

diff --git a/crates/polars-sql/src/functions.rs b/crates/polars-sql/src/functions.rs
index 5822aa8086bf..c605271b9f4e 100644
--- a/crates/polars-sql/src/functions.rs
+++ b/crates/polars-sql/src/functions.rs
@@ -23,186 +23,236 @@ pub(crate) enum PolarsSqlFunctions {
     // Math functions
     // ----
     /// SQL 'abs' function
+    /// Returns the absolute value of the input column
     /// ```sql
     /// SELECT ABS(column_1) from df;
     /// ```
     Abs,
     /// SQL 'cos' function
+    /// Compute the cosine sine of the input column (in radians)
     /// ```sql
     /// SELECT COS(column_1) from df;
     /// ```
     Cos,
     /// SQL 'cot' function
+    /// Compute the cotangent of the input column (in radians)
     /// ```sql
     /// SELECT COT(column_1) from df;
     /// ```
     Cot,
     /// SQL 'sin' function
+    /// Compute the sine of the input column (in radians)
     /// ```sql
     /// SELECT SIN(column_1) from df;
     /// ```
     Sin,
     /// SQL 'tan' function
+    /// Compute the tangent of the input column (in radians)
     /// ```sql
     /// SELECT TAN(column_1) from df;
     /// ```
     Tan,
     /// SQL 'cosd' function
+    /// Compute the cosine sine of the input column (in degrees)
     /// ```sql
     /// SELECT COSD(column_1) from df;
     /// ```
     CosD,
     /// SQL 'cotd' function
+    /// Compute cotangent of the input column (in degrees)
     /// ```sql
     /// SELECT COTD(column_1) from df;
     /// ```
     CotD,
     /// SQL 'sind' function
+    /// Compute the sine of the input column (in degrees)
     /// ```sql
     /// SELECT SIND(column_1) from df;
     /// ```
     SinD,
     /// SQL 'tand' function
+    /// Compute the tangent of the input column (in degrees)
     /// ```sql
     /// SELECT TAND(column_1) from df;
     /// ```
     TanD,
     /// SQL 'acos' function
+    /// Compute inverse cosinus of the input column (in radians)
     /// ```sql
     /// SELECT ACOS(column_1) from df;
     /// ```
     Acos,
     /// SQL 'asin' function
+    /// Compute inverse sine of the input column (in radians)
     /// ```sql
     /// SELECT ASIN(column_1) from df;
     /// ```
     Asin,
     /// SQL 'atan' function
+    /// Compute inverse tangent of the input column (in radians)
     /// ```sql
     /// SELECT ATAN(column_1) from df;
     /// ```
     Atan,
     /// SQL 'atan2' function
+    /// Compute the inverse tangent of column_2/column_1 (in radians).
     /// ```sql
-    /// SELECT ATAN2(column_1) from df;
+    /// SELECT ATAN2(column_1, column_2) from df;
     /// ```
     Atan2,
     /// SQL 'acosd' function
+    /// Compute inverse cosinus of the input column (in degrees)
     /// ```sql
     /// SELECT ACOSD(column_1) from df;
     /// ```
     AcosD,
     /// SQL 'asind' function
+    /// Compute inverse sine of the input column (in degrees)
     /// ```sql
     /// SELECT ASIND(column_1) from df;
     /// ```
     AsinD,
     /// SQL 'atand' function
+    /// Compute inverse tangent of the input column (in degrees)
     /// ```sql
     /// SELECT ATAND(column_1) from df;
     /// ```
     AtanD,
     /// SQL 'atan2d' function
+    /// Compute the inverse tangent of column_2/column_1 (in degrees).
     /// ```sql
     /// SELECT ATAN2D(column_1) from df;
     /// ```
     Atan2D,
     /// SQL 'ceil' function
+    /// Returns the nearest integer closest from zero.
     /// ```sql
     /// SELECT CEIL(column_1) from df;
     /// ```
     Ceil,
     /// SQL 'exp' function
+    /// Computes the exponential of the given value.
     /// ```sql
     /// SELECT EXP(column_1) from df;
     /// ```
     Exp,
     /// SQL 'floor' function
+    /// Returns the nearest integer away from zero.
+    ///   0.5 will be rounded
     /// ```sql
     /// SELECT FLOOR(column_1) from df;
     /// ```
     Floor,
     /// SQL 'pi' function
+    /// Returns a (very good) approximation of 𝜋
     /// ```sql
     /// SELECT PI() from df;
     /// ```
     Pi,
     /// SQL 'ln' function
+    /// Computes the natural logarithm of the given value
     /// ```sql
     /// SELECT LN(column_1) from df;
     /// ```
     Ln,
     /// SQL 'log2' function
+    /// Computes the logarithm of the given value in base 2
     /// ```sql
     /// SELECT LOG2(column_1) from df;
     /// ```
     Log2,
     /// SQL 'log10' function
+    /// Computes the logarithm of the given value in base 10
     /// ```sql
     /// SELECT LOG10(column_1) from df;
     /// ```
     Log10,
     /// SQL 'log' function
+    /// Computes the `base` logarithm of the given value
     /// ```sql
     /// SELECT LOG(column_1, 10) from df;
     /// ```
     Log,
     /// SQL 'log1p' function
+    /// Computes the natural logarithm of the “given value plus one”
     /// ```sql
     /// SELECT LOG1P(column_1) from df;
     /// ```
     Log1p,
     /// SQL 'pow' function
+    /// Returns the value to the power of `exponent`
     /// ```sql
     /// SELECT POW(column_1, 2) from df;
     /// ```
     Pow,
     /// SQL 'sqrt' function
+    /// Returns the square root (√) of a number
     /// ```sql
     /// SELECT SQRT(column_1) from df;
     /// ```
     Sqrt,
     /// SQL 'cbrt' function
+    /// Returns the cube root (∛) of a number
     /// ```sql
     /// SELECT CBRT(column_1) from df;
     /// ```
     Cbrt,
     /// SQL 'round' function
+    /// Round a number to `x` decimals (default: 0) away from zero.
+    ///   .5 is rounded away from zero.
     /// ```sql
     /// SELECT ROUND(column_1, 3) from df;
     /// ```
     Round,
+    /// SQL 'degrees' function
+    /// Convert between radians and degrees
+    /// ```sql
+    /// SELECT DEGREES(column_1) from df;
+    /// ```
+    Degrees,
+    /// SQL 'RADIANS' function
+    /// Convert between degrees and radians
+    /// ```sql
+    /// SELECT radians(column_1) from df;
+    /// ```
+    Radians,
 
     // ----
     // String functions
     // ----
     /// SQL 'ends_with' function
+    /// Returns True if the value ends with the second argument.
     /// ```sql
     /// SELECT ENDS_WITH(column_1, 'a') from df;
     /// SELECT column_2 from df WHERE ENDS_WITH(column_1, 'a');
     /// ```
     EndsWith,
     /// SQL 'initcap' function
+    /// Returns the value with the first letter capitalized
     /// ```sql
     /// SELECT INITCAP(column_1) from df;
     /// ```
     InitCap,
     /// SQL 'left' function
+    /// Returns the `length` first characters
     /// ```sql
     /// SELECT LEFT(column_1, 3) from df;
     /// ```
     Left,
     /// SQL 'length' function (characters)
+    /// Returns the character length of the string
     /// ```sql
     /// SELECT LENGTH(column_1) from df;
     /// ```
     Length,
     /// SQL 'lower' function
+    /// Returns an lowercased column
     /// ```sql
     /// SELECT LOWER(column_1) from df;
     /// ```
     Lower,
     /// SQL 'ltrim' function
+    /// Strip whitespaces from the left
     /// ```sql
     /// SELECT LTRIM(column_1) from df;
     /// ```
@@ -213,37 +263,45 @@ pub(crate) enum PolarsSqlFunctions {
     /// ```
     OctetLength,
     /// SQL 'regexp_like' function
+    /// True if `pattern` matches the value (optional: `flags`).
     /// ```sql
-    /// SELECT REGEXP_LIKE(column_1,'xyz', 'i') from df;
+    /// SELECT REGEXP_LIKE(column_1, 'xyz', 'i') from df;
     /// ```
     RegexpLike,
     /// SQL 'rtrim' function
+    /// Strip whitespaces from the right
     /// ```sql
     /// SELECT RTRIM(column_1) from df;
     /// ```
     RTrim,
     /// SQL 'starts_with' function
+    /// Returns True if the value starts with the second argument.
     /// ```sql
     /// SELECT STARTS_WITH(column_1, 'a') from df;
     /// SELECT column_2 from df WHERE STARTS_WITH(column_1, 'a');
     /// ```
     StartsWith,
     /// SQL 'substr' function
+    /// Returns a portion of the data (first character = 0) in the range
+    ///   \[start, start + length]
     /// ```sql
     /// SELECT SUBSTR(column_1, 3, 5) from df;
     /// ```
     Substring,
     /// SQL 'upper' function
+    /// Returns an uppercased column
     /// ```sql
     /// SELECT UPPER(column_1) from df;
     /// ```
     Upper,
     /// SQL 'nullif' function
+    /// Returns NULL if two expressions are equal, otherwise returns the first
     /// ```sql
     /// SELECT NULLIF(column_1, column_2) from df;
     /// ```
     NullIf,
     /// SQL 'coalesce' function
+    /// Returns the first non-null value in the provided values/columns
     /// ```sql
     /// SELECT COALESCE(column_1, ...) from df;
     /// ```
@@ -253,6 +311,7 @@ pub(crate) enum PolarsSqlFunctions {
     // Aggregate functions
     // ----
     /// SQL 'count' function
+    /// Returns the amount of elements in the grouping
     /// ```sql
     /// SELECT COUNT(column_1) from df;
     /// SELECT COUNT(*) from df;
@@ -261,41 +320,49 @@ pub(crate) enum PolarsSqlFunctions {
     /// ```
     Count,
     /// SQL 'sum' function
+    /// Returns the sum of all the elements in the grouping
     /// ```sql
     /// SELECT SUM(column_1) from df;
     /// ```
     Sum,
     /// SQL 'min' function
+    /// Returns the smallest (minimum) of all the elements in the grouping
     /// ```sql
     /// SELECT MIN(column_1) from df;
     /// ```
     Min,
     /// SQL 'max' function
+    /// Returns the greatest (maximum) of all the elements in the grouping
     /// ```sql
     /// SELECT MAX(column_1) from df;
     /// ```
     Max,
     /// SQL 'avg' function
+    /// Returns the average (mean) of all the elements in the grouping
     /// ```sql
     /// SELECT AVG(column_1) from df;
     /// ```
     Avg,
     /// SQL 'stddev' function
+    /// Returns the standard deviation of all the elements in the grouping
     /// ```sql
     /// SELECT STDDEV(column_1) from df;
     /// ```
     StdDev,
     /// SQL 'variance' function
+    /// Returns the variance of all the elements in the grouping
     /// ```sql
     /// SELECT VARIANCE(column_1) from df;
     /// ```
     Variance,
     /// SQL 'first' function
+    /// Returns the first element of the grouping
     /// ```sql
     /// SELECT FIRST(column_1) from df;
     /// ```
     First,
     /// SQL 'last' function
+    /// Returns the last element of the grouping
     /// ```sql
     /// SELECT LAST(column_1) from df;
     /// ```
@@ -305,20 +372,11 @@ pub(crate) enum PolarsSqlFunctions {
     // Array functions
     // ----
     /// SQL 'array_length' function
+    /// Returns the length of the array
     /// ```sql
     /// SELECT ARRAY_LENGTH(column_1) from df;
     /// ```
     ArrayLength,
-    /// SQL 'degrees' function
-    /// ```sql
-    /// SELECT DEGREES(column_1) from df;
-    /// ```
-    Degrees,
-    /// SQL 'RADIANS' function
-    /// ```sql
-    /// SELECT radians(column_1) from df;
-    /// ```
-    Radians,
     /// SQL 'array_lower' function
     /// Returns the minimum value in an array; equivalent to `array_min`
     /// ```sql
@@ -356,12 +414,13 @@ pub(crate) enum PolarsSqlFunctions {
     /// ```
     ArrayUnique,
     /// SQL 'unnest' function
-    /// unnest/explods an array column into multiple rows
+    /// Unnest/explodes an array column into multiple rows
     /// ```sql
     /// SELECT unnest(column_1) from df;
     /// ```
     Explode,
     /// SQL 'array_to_string' function
+    /// Takes all elements of the array and joins them into one string
     /// ```sql
     /// SELECT ARRAY_TO_STRING(column_1, ', ') from df;
     /// ```