From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 22 Aug 2022 17:43:59 +0000 (-0400)
Subject: reformat functions.rst; document coalsce
X-Git-Tag: rel_2_0_0b1~97
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=07961a8bd0b965d79855275b0eb80075b57c2d49;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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
---

diff --git a/doc/build/core/functions.rst b/doc/build/core/functions.rst
index 8a3c5221fd..00e384679c 100644
--- 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: