Improve function documentation (apache#11996)

datafusion/functions/src/core/mod.rs

@@ -86,6 +86,7 @@ pub mod expr_fn {
     }
 }
 
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<Arc<ScalarUDF>> {
     vec![
         nullif(),
@@ -94,6 +95,13 @@ pub fn functions() -> Vec<Arc<ScalarUDF>> {
         nvl2(),
         arrow_typeof(),
         named_struct(),
+        // Note: most users invoke `get_field` indirectly via field access
+        // syntax like `my_struct_col['field_name']`, which results in a call to
+        // `get_field(my_struct_col, "field_name")`.
+        //
+        // However, it is also exposed directly for use cases such as
+        // serializing / deserializing plans with the field access  desugared to
+        // calls to `get_field`
         get_field(),
         coalesce(),
     ]

datafusion/functions/src/crypto/mod.rs

@@ -62,6 +62,7 @@ pub mod expr_fn {
     ));
 }
 
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<Arc<ScalarUDF>> {
     vec![digest(), md5(), sha224(), sha256(), sha384(), sha512()]
 }

datafusion/functions/src/datetime/mod.rs

@@ -272,7 +272,7 @@ pub mod expr_fn {
     }
 }
 
-///   Return a list of all functions in this package
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<Arc<ScalarUDF>> {
     vec![
         current_date(),

datafusion/functions/src/encoding/mod.rs

@@ -37,6 +37,7 @@ pub mod expr_fn {
     ));
 }
 
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<Arc<ScalarUDF>> {
     vec![encode(), decode()]
 }

datafusion/functions/src/math/mod.rs

@@ -276,6 +276,7 @@ pub mod expr_fn {
     );
 }
 
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<Arc<ScalarUDF>> {
     vec![
         abs(),

datafusion/functions/src/regex/mod.rs

@@ -65,7 +65,7 @@ pub mod expr_fn {
     }
 }
 
-#[doc = r" Return a list of all functions in this package"]
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<std::sync::Arc<datafusion_expr::ScalarUDF>> {
     vec![regexp_match(), regexp_like(), regexp_replace()]
 }

datafusion/functions/src/string/mod.rs

@@ -167,7 +167,7 @@ pub mod expr_fn {
     }
 }
 
-///   Return a list of all functions in this package
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<Arc<ScalarUDF>> {
     vec![
         ascii(),

datafusion/functions/src/unicode/mod.rs

@@ -125,7 +125,7 @@ pub mod expr_fn {
     }
 }
 
-///   Return a list of all functions in this package
+/// Returns all DataFusion functions defined in this package
 pub fn functions() -> Vec<Arc<ScalarUDF>> {
     vec![
         character_length(),