fix func docs

sphinx is not generating the docs for func.  cross-copy
__doc__ and also add more links.

Fixes: #4922
Change-Id: I5512111d726b6fcf9821be730c9e29adc73c95cb

1 files changed, 108 insertions, 69 deletions

diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index 2feb6fd5f..4a26f8921 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -66,6 +66,8 @@ class FunctionElement(Executable, ColumnElement, FromClause):
 
     .. seealso::
 
+        :ref:`coretutorial_functions` - in the Core tutorial
+
         :class:`.Function` - named SQL function.
 
         :data:`.func` - namespace which produces registered or ad-hoc
@@ -81,7 +83,20 @@ class FunctionElement(Executable, ColumnElement, FromClause):
     _has_args = False
 
     def __init__(self, *clauses, **kwargs):
-        """Construct a :class:`.FunctionElement`.
+        r"""Construct a :class:`.FunctionElement`.
+
+        :param \*clauses: list of column expressions that form the arguments
+         of the SQL function call.
+
+        :param \**kwargs:  additional kwargs are typically consumed by
+         subclasses.
+
+        .. seealso::
+
+            :data:`.func`
+
+            :class:`.Function`
+
         """
         args = [
             coercions.expect(
@@ -432,7 +447,80 @@ class FunctionAsBinary(BinaryExpression):
 
 
 class _FunctionGenerator(object):
-    """Generate :class:`.Function` objects based on getattr calls."""
+    """Generate SQL function expressions.
+
+    :data:`.func` is a special object instance which generates SQL
+    functions based on name-based attributes, e.g.::
+
+        >>> print(func.count(1))
+        count(:param_1)
+
+    The returned object is an instance of :class:`.Function`, and  is a
+    column-oriented SQL element like any other, and is used in that way::
+
+        >>> print(select([func.count(table.c.id)]))
+        SELECT count(sometable.id) FROM sometable
+
+    Any name can be given to :data:`.func`. If the function name is unknown to
+    SQLAlchemy, it will be rendered exactly as is. For common SQL functions
+    which SQLAlchemy is aware of, the name may be interpreted as a *generic
+    function* which will be compiled appropriately to the target database::
+
+        >>> print(func.current_timestamp())
+        CURRENT_TIMESTAMP
+
+    To call functions which are present in dot-separated packages,
+    specify them in the same manner::
+
+        >>> print(func.stats.yield_curve(5, 10))
+        stats.yield_curve(:yield_curve_1, :yield_curve_2)
+
+    SQLAlchemy can be made aware of the return type of functions to enable
+    type-specific lexical and result-based behavior. For example, to ensure
+    that a string-based function returns a Unicode value and is similarly
+    treated as a string in expressions, specify
+    :class:`~sqlalchemy.types.Unicode` as the type:
+
+        >>> print(func.my_string(u'hi', type_=Unicode) + ' ' +
+        ...       func.my_string(u'there', type_=Unicode))
+        my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)
+
+    The object returned by a :data:`.func` call is usually an instance of
+    :class:`.Function`.
+    This object meets the "column" interface, including comparison and labeling
+    functions.  The object can also be passed the :meth:`~.Connectable.execute`
+    method of a :class:`.Connection` or :class:`.Engine`, where it will be
+    wrapped inside of a SELECT statement first::
+
+        print(connection.execute(func.current_timestamp()).scalar())
+
+    In a few exception cases, the :data:`.func` accessor
+    will redirect a name to a built-in expression such as :func:`.cast`
+    or :func:`.extract`, as these names have well-known meaning
+    but are not exactly the same as "functions" from a SQLAlchemy
+    perspective.
+
+    Functions which are interpreted as "generic" functions know how to
+    calculate their return type automatically. For a listing of known generic
+    functions, see :ref:`generic_functions`.
+
+    .. note::
+
+        The :data:`.func` construct has only limited support for calling
+        standalone "stored procedures", especially those with special
+        parameterization concerns.
+
+        See the section :ref:`stored_procedures` for details on how to use
+        the DBAPI-level ``callproc()`` method for fully traditional stored
+        procedures.
+
+    .. seealso::
+
+        :ref:`coretutorial_functions` - in the Core Tutorial
+
+        :class:`.Function`
+
+    """
 
     def __init__(self, **opts):
         self.__names = []
@@ -477,86 +565,37 @@ class _FunctionGenerator(object):
 
 
 func = _FunctionGenerator()
-"""Generate SQL function expressions.
-
-   :data:`.func` is a special object instance which generates SQL
-   functions based on name-based attributes, e.g.::
-
-        >>> print(func.count(1))
-        count(:param_1)
-
-   The element is a column-oriented SQL element like any other, and is
-   used in that way::
-
-        >>> print(select([func.count(table.c.id)]))
-        SELECT count(sometable.id) FROM sometable
-
-   Any name can be given to :data:`.func`. If the function name is unknown to
-   SQLAlchemy, it will be rendered exactly as is. For common SQL functions
-   which SQLAlchemy is aware of, the name may be interpreted as a *generic
-   function* which will be compiled appropriately to the target database::
-
-        >>> print(func.current_timestamp())
-        CURRENT_TIMESTAMP
-
-   To call functions which are present in dot-separated packages,
-   specify them in the same manner::
-
-        >>> print(func.stats.yield_curve(5, 10))
-        stats.yield_curve(:yield_curve_1, :yield_curve_2)
+func.__doc__ = _FunctionGenerator.__doc__
 
-   SQLAlchemy can be made aware of the return type of functions to enable
-   type-specific lexical and result-based behavior. For example, to ensure
-   that a string-based function returns a Unicode value and is similarly
-   treated as a string in expressions, specify
-   :class:`~sqlalchemy.types.Unicode` as the type:
+modifier = _FunctionGenerator(group=False)
 
-        >>> print(func.my_string(u'hi', type_=Unicode) + ' ' +
-        ...       func.my_string(u'there', type_=Unicode))
-        my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)
 
-   The object returned by a :data:`.func` call is usually an instance of
-   :class:`.Function`.
-   This object meets the "column" interface, including comparison and labeling
-   functions.  The object can also be passed the :meth:`~.Connectable.execute`
-   method of a :class:`.Connection` or :class:`.Engine`, where it will be
-   wrapped inside of a SELECT statement first::
+class Function(FunctionElement):
+    r"""Describe a named SQL function.
 
-        print(connection.execute(func.current_timestamp()).scalar())
+    The :class:`.Function` object is typically generated from the
+    :data:`.func` generation object.
 
-   In a few exception cases, the :data:`.func` accessor
-   will redirect a name to a built-in expression such as :func:`.cast`
-   or :func:`.extract`, as these names have well-known meaning
-   but are not exactly the same as "functions" from a SQLAlchemy
-   perspective.
 
-   Functions which are interpreted as "generic" functions know how to
-   calculate their return type automatically. For a listing of known generic
-   functions, see :ref:`generic_functions`.
+    :param \*clauses: list of column expressions that form the arguments
+     of the SQL function call.
 
-   .. note::
+    :param type_: optional :class:`.TypeEngine` datatype object that will be
+     used as the return value of the column expression generated by this
+     function call.
 
-        The :data:`.func` construct has only limited support for calling
-        standalone "stored procedures", especially those with special
-        parameterization concerns.
-
-        See the section :ref:`stored_procedures` for details on how to use
-        the DBAPI-level ``callproc()`` method for fully traditional stored
-        procedures.
-
-"""
-
-modifier = _FunctionGenerator(group=False)
+    :param packagenames: a string which indicates package prefix names
+     to be prepended to the function name when the SQL is generated.
+     The :data:`.func` generator creates these when it is called using
+     dotted format, e.g.::
 
+        func.mypackage.some_function(col1, col2)
 
-class Function(FunctionElement):
-    """Describe a named SQL function.
-
-    See the superclass :class:`.FunctionElement` for a description
-    of public methods.
 
     .. seealso::
 
+        :ref:`coretutorial_functions`
+
         :data:`.func` - namespace which produces registered or ad-hoc
         :class:`.Function` instances.