reformat functions.rst; document coalsce

this file was all over the place autodocumenting all the
contents of functions.py with no regards to the heading
paragraph which seemed to be introducing the generic functions.
Use specific autoclass/autofunc docs as automodule is generally
unworkable.

Add missing docstring for coalesce function.

Fixes: #8415
Change-Id: I4c37e6153282ce99b9f5d674f6e802c25ef536e1
(cherry picked from commit 07961a8bd0b965d79855275b0eb80075b57c2d49)

diff --git a/doc/build/core/functions.rst b/doc/build/core/functions.rst
index 8a3c5221fd15670f46da42923f832f2891e408b6..00e384679cc4c21a0e810712d177e89a2531c9d1 100644 (file)
--- a/doc/build/core/functions.rst
+++ b/doc/build/core/functions.rst
@@ -7,24 +7,140 @@ SQL and Generic Functions
 
 .. currentmodule:: sqlalchemy.sql.functions
 
-SQL functions which are known to SQLAlchemy with regards to database-specific
-rendering, return types and argument behavior. Generic functions are invoked
-like all SQL functions, using the :attr:`func` attribute::
+SQL functions are invoked by using the :data:`_sql.func` namespace.
+See the tutorial at :ref:`tutorial_functions` for background on how to
+use the :data:`_sql.func` object to render SQL functions in statements.
 
-    select(func.count()).select_from(sometable)
+.. seealso::
+
+    :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
+
+Function API
+------------
+
+The base API for SQL functions, which provides for the :data:`_sql.func`
+namespace as well as classes that may be used for extensibility.
+
+.. autoclass:: AnsiFunction
+   :exclude-members: inherit_cache, __new__
+
+.. autoclass:: Function
+   :members:
+   :inherited-members: ColumnElement
+   :exclude-members: inherit_cache, __new__
+
+.. autoclass:: FunctionElement
+   :members:
+   :exclude-members: inherit_cache, __new__
+
+.. autoclass:: GenericFunction
+   :exclude-members: inherit_cache, __new__
 
-Note that any name not known to :attr:`func` generates the function name as is
-- there is no restriction on what SQL functions can be called, known or
+.. autofunction:: register_function
+
+
+Selected "Known" Functions
+--------------------------
+
+These are :class:`.GenericFunction` implementations for a selected set of
+common SQL functions that set up the expected return type for each function
+automatically.  The are invoked in the same way as any other member of the
+:data:`_sql.func` namespace::
+
+    select(func.count('*')).select_from(some_table)
+
+Note that any name not known to :data:`_sql.func` generates the function name
+as is - there is no restriction on what SQL functions can be called, known or
 unknown to SQLAlchemy, built-in or user defined. The section here only
 describes those functions where SQLAlchemy already knows what argument and
 return types are in use.
 
-.. seealso::
+.. autoclass:: array_agg
+    :no-members:
 
-    :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
+.. autoclass:: char_length
+    :no-members:
 
-.. automodule:: sqlalchemy.sql.functions
-   :members:
-   :exclude-members: func
+.. autoclass:: coalesce
+    :no-members:
+
+.. autoclass:: concat
+    :no-members:
+
+.. autoclass:: count
+    :no-members:
+
+.. autoclass:: cube
+    :no-members:
+
+.. autoclass:: cume_dist
+    :no-members:
+
+.. autoclass:: current_date
+    :no-members:
+
+.. autoclass:: current_time
+    :no-members:
+
+.. autoclass:: current_timestamp
+    :no-members:
+
+.. autoclass:: current_user
+    :no-members:
+
+.. autoclass:: dense_rank
+    :no-members:
+
+.. autoclass:: grouping_sets
+    :no-members:
+
+.. autoclass:: localtime
+    :no-members:
+
+.. autoclass:: localtimestamp
+    :no-members:
+
+.. autoclass:: max
+    :no-members:
+
+.. autoclass:: min
+    :no-members:
+
+.. autoclass:: mode
+    :no-members:
+
+.. autoclass:: next_value
+    :no-members:
+
+.. autoclass:: now
+    :no-members:
+
+.. autoclass:: percent_rank
+    :no-members:
+
+.. autoclass:: percentile_cont
+    :no-members:
+
+.. autoclass:: percentile_disc
+    :no-members:
+
+.. autoclass:: random
+    :no-members:
+
+.. autoclass:: rank
+    :no-members:
+
+.. autoclass:: rollup
+    :no-members:
+
+.. autoclass:: session_user
+    :no-members:
+
+.. autoclass:: sum
+    :no-members:
 
+.. autoclass:: sysdate
+    :no-members:
 
+.. autoclass:: user
+    :no-members: