[docs]: added alternative_syntax function for docs (#13140)

* Add alternative syntax function.

* fmt check

Author: jonathanc-n

datafusion/core/src/bin/print_functions_docs.rs

@@ -195,6 +195,13 @@ fn print_docs(
                 );
             }
 
+            if let Some(alt_syntax) = &documentation.alternative_syntax {
+                let _ = writeln!(docs, "#### Alternative Syntax\n");
+                for syntax in alt_syntax {
+                    let _ = writeln!(docs, "```sql\n{}\n```", syntax);
+                }
+            }
+
             // next, aliases
             if !f.get_aliases().is_empty() {
                 let _ = writeln!(docs, "#### Aliases");

datafusion/expr/src/udf_docs.rs

@@ -47,6 +47,8 @@ pub struct Documentation {
     /// Left member of a pair is the argument name, right is a
     /// description for the argument
     pub arguments: Option<Vec<(String, String)>>,
+    /// A list of alternative syntax examples for a function
+    pub alternative_syntax: Option<Vec<String>>,
     /// Related functions if any. Values should match the related
     /// udf's name exactly. Related udf's must be of the same
     /// UDF type (scalar, aggregate or window) for proper linking to
@@ -96,6 +98,7 @@ pub struct DocumentationBuilder {
     pub syntax_example: Option<String>,
     pub sql_example: Option<String>,
     pub arguments: Option<Vec<(String, String)>>,
+    pub alternative_syntax: Option<Vec<String>>,
     pub related_udfs: Option<Vec<String>>,
 }
 
@@ -107,6 +110,7 @@ impl DocumentationBuilder {
             syntax_example: None,
             sql_example: None,
             arguments: None,
+            alternative_syntax: None,
             related_udfs: None,
         }
     }
@@ -172,6 +176,13 @@ impl DocumentationBuilder {
         self.with_argument(arg_name, description)
     }
 
+    pub fn with_alternative_syntax(mut self, syntax_name: impl Into<String>) -> Self {
+        let mut alternative_syntax_array = self.alternative_syntax.unwrap_or_default();
+        alternative_syntax_array.push(syntax_name.into());
+        self.alternative_syntax = Some(alternative_syntax_array);
+        self
+    }
+
     pub fn with_related_udf(mut self, related_udf: impl Into<String>) -> Self {
         let mut related = self.related_udfs.unwrap_or_default();
         related.push(related_udf.into());
@@ -186,6 +197,7 @@ impl DocumentationBuilder {
             syntax_example,
             sql_example,
             arguments,
+            alternative_syntax,
             related_udfs,
         } = self;
 
@@ -205,6 +217,7 @@ impl DocumentationBuilder {
             syntax_example: syntax_example.unwrap(),
             sql_example,
             arguments,
+            alternative_syntax,
             related_udfs,
         })
     }

datafusion/functions/src/unicode/strpos.rs

@@ -97,6 +97,7 @@ fn get_strpos_doc() -> &'static Documentation {
 ```"#)
             .with_standard_argument("str", Some("String"))
             .with_argument("substr", "Substring expression to search for.")
+            .with_alternative_syntax("position(substr in origstr)")
             .build()
             .unwrap()
     })

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

@@ -1465,6 +1465,12 @@ strpos(str, substr)
 +----------------------------------------+
 ```
 
+#### Alternative Syntax
+
+```sql
+position(substr in origstr)
+```
+
 #### Aliases
 
 - instr