Port / Add Documentation for VarianceSample and VariancePopulation (#12742)

Author: alamb

datafusion/functions-aggregate/src/variance.rs

@@ -18,22 +18,24 @@
 //! [`VarianceSample`]: variance sample aggregations.
 //! [`VariancePopulation`]: variance population aggregations.
 
-use std::{fmt::Debug, sync::Arc};
-
 use arrow::{
     array::{Array, ArrayRef, BooleanArray, Float64Array, UInt64Array},
     buffer::NullBuffer,
     compute::kernels::cast,
     datatypes::{DataType, Field},
 };
+use std::sync::OnceLock;
+use std::{fmt::Debug, sync::Arc};
 
 use datafusion_common::{
     downcast_value, not_impl_err, plan_err, DataFusionError, Result, ScalarValue,
 };
+use datafusion_expr::aggregate_doc_sections::DOC_SECTION_GENERAL;
 use datafusion_expr::{
     function::{AccumulatorArgs, StateFieldsArgs},
     utils::format_state_name,
-    Accumulator, AggregateUDFImpl, GroupsAccumulator, Signature, Volatility,
+    Accumulator, AggregateUDFImpl, Documentation, GroupsAccumulator, Signature,
+    Volatility,
 };
 use datafusion_functions_aggregate_common::{
     aggregate::groups_accumulator::accumulate::accumulate, stats::StatsType,
@@ -135,6 +137,26 @@ impl AggregateUDFImpl for VarianceSample {
     ) -> Result<Box<dyn GroupsAccumulator>> {
         Ok(Box::new(VarianceGroupsAccumulator::new(StatsType::Sample)))
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_variance_sample_doc())
+    }
+}
+
+static VARIANCE_SAMPLE_DOC: OnceLock<Documentation> = OnceLock::new();
+
+fn get_variance_sample_doc() -> &'static Documentation {
+    VARIANCE_SAMPLE_DOC.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_GENERAL)
+            .with_description(
+                "Returns the statistical sample variance of a set of numbers.",
+            )
+            .with_syntax_example("var(expression)")
+            .with_standard_argument("expression", "Numeric")
+            .build()
+            .unwrap()
+    })
 }
 
 pub struct VariancePopulation {
@@ -222,6 +244,25 @@ impl AggregateUDFImpl for VariancePopulation {
             StatsType::Population,
         )))
     }
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_variance_population_doc())
+    }
+}
+
+static VARIANCE_POPULATION_DOC: OnceLock<Documentation> = OnceLock::new();
+
+fn get_variance_population_doc() -> &'static Documentation {
+    VARIANCE_POPULATION_DOC.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_GENERAL)
+            .with_description(
+                "Returns the statistical population variance of a set of numbers.",
+            )
+            .with_syntax_example("var_pop(expression)")
+            .with_standard_argument("expression", "Numeric")
+            .build()
+            .unwrap()
+    })
 }
 
 /// An accumulator to compute variance

docs/source/user-guide/sql/aggregate_functions.md

@@ -240,9 +240,6 @@ last_value(expression [ORDER BY expression])
 - [stddev](#stddev)
 - [stddev_pop](#stddev_pop)
 - [stddev_samp](#stddev_samp)
-- [var](#var)
-- [var_pop](#var_pop)
-- [var_samp](#var_samp)
 - [regr_avgx](#regr_avgx)
 - [regr_avgy](#regr_avgy)
 - [regr_count](#regr_count)
@@ -349,45 +346,6 @@ stddev_samp(expression)
 
 #### Arguments
 
-- **expression**: Expression to operate on.
-  Can be a constant, column, or function, and any combination of arithmetic operators.
-
-### `var`
-
-Returns the statistical variance of a set of numbers.
-
-```
-var(expression)
-```
-
-#### Arguments
-
-- **expression**: Expression to operate on.
-  Can be a constant, column, or function, and any combination of arithmetic operators.
-
-### `var_pop`
-
-Returns the statistical population variance of a set of numbers.
-
-```
-var_pop(expression)
-```
-
-#### Arguments
-
-- **expression**: Expression to operate on.
-  Can be a constant, column, or function, and any combination of arithmetic operators.
-
-### `var_samp`
-
-Returns the statistical sample variance of a set of numbers.
-
-```
-var_samp(expression)
-```
-
-#### Arguments
-
 - **expression**: Expression to operate on.
   Can be a constant, column, or function, and any combination of arithmetic operators.
 

docs/source/user-guide/sql/aggregate_functions_new.md

@@ -36,6 +36,11 @@ Aggregate functions operate on a set of values to compute a single result.
 - [bit_and](#bit_and)
 - [bit_or](#bit_or)
 - [bit_xor](#bit_xor)
+- [var](#var)
+- [var_pop](#var_pop)
+- [var_population](#var_population)
+- [var_samp](#var_samp)
+- [var_sample](#var_sample)
 
 ### `bit_and`
 
@@ -72,3 +77,79 @@ bit_xor(expression)
 #### Arguments
 
 - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators.
+
+### `var`
+
+Returns the statistical sample variance of a set of numbers.
+
+```
+var(expression)
+```
+
+#### Arguments
+
+- **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators.
+
+#### Aliases- var_sample
+
+- var_samp
+
+### `var_pop`
+
+Returns the statistical population variance of a set of numbers.
+
+```
+var_pop(expression)
+```
+
+#### Arguments
+
+- **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators.
+
+#### Aliases- var_population
+
+### `var_pop`
+
+Returns the statistical population variance of a set of numbers.
+
+```
+var_pop(expression)
+```
+
+#### Arguments
+
+- **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators.
+
+#### Aliases- var_population
+
+### `var`
+
+Returns the statistical sample variance of a set of numbers.
+
+```
+var(expression)
+```
+
+#### Arguments
+
+- **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators.
+
+#### Aliases- var_sample
+
+- var_samp
+
+### `var`
+
+Returns the statistical sample variance of a set of numbers.
+
+```
+var(expression)
+```
+
+#### Arguments
+
+- **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators.
+
+#### Aliases- var_sample
+
+- var_samp