add examples and description to scalar/aggregate functions?

[universalmind303]

Is your feature request related to a problem or challenge?

Currently I am working on adding examples & documentation to all sql functions for a database implementation built on datafusion. GlareDB. We are manually providing examples and docs for all of the functions native to datafusion. It'd be nice if these were provided by datafusion out of the box.

Describe the solution you'd like

in addition to name, and signature, BuiltinScalarFunction and AggregateFunction should provide methods for description & example usage.

let abs = BuiltinScalarFunction::Abs;
abs.name() // "abs"
abs.sql_example() // "abs(-1)"
abs.description() //  "Compute the absolute value of a number."

Describe alternatives you've considered

See above.

Additional context

Considering we've (glaredb) already implemented the examples/descriptions for our own usecase, I'd be happy to submit a PR to add it to datafusion if it's something that would benefit others. One thing to consider is that it may add a bit of bloat to binaries as it'll need to contain all of these additional strings. (maybe we could/should feature flag it?)

[alamb]

Thank you @universalmind303 -- I think adding this information would be sweet (even sweeter if if we could automatically update the user guide like we do with the configuration settings here: https://github.com/apache/arrow-datafusion/blob/main/dev/update_config_docs.sh

In terms of binary bloat, one thing you could do would be to add the description and examples as comments and then scrape the comments into the docs.

However, that would not allow you to make the table from https://github.com/GlareDB/glaredb/pull/2178/files#diff-5465ce3e9dc3e728014534444ea0ea2be837da7e0d77d73756a2282d3f805771

Also, FYI longer term I have a plan to make it easier to include just a subset of datafusion functions (and aggregate functions), which i am tracking here: #8045, which I think can help signifiicantly (among other things the hope is to remove BuiltInScalarFunction (and replace with just ScalarUDF))

[alamb]

We have completed this work as part of #12432 (thanks @Omega359 @jonathanc-n and others)

[alamb]

For example

https://docs.rs/datafusion/latest/datafusion/logical_expr/trait.AggregateUDFImpl.html#method.documentation

and you can set various fields like this: https://docs.rs/datafusion/latest/datafusion/logical_expr/struct.Documentation.html