use ..deprecated directive w/ version in all cases

These changes should be ported from 1.3 back to 1.0 or
possibly 0.9 to the extent they are relevant in each
version. In 1.3 we hope to turn all deprecation documentation
into warnings.

Change-Id: I205186cde161af9389af513a425c62ce90dd54d8

7 files changed, 160 insertions, 92 deletions

diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index c752da013..f221fb00a 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -312,7 +312,10 @@ class Compiled(object):
 
     @util.deprecated(
         "0.7",
-        ":class:`.Compiled` objects now compile " "within the constructor.",
+        "The :meth:`.Compiled.compile` method is deprecated and will be "
+        "removed in a future release.   The :class:`.Compiled` object "
+        "now runs its compilation within the constructor, and this method "
+        "does nothing."
     )
     def compile(self):
         """Produce the internal string representation of this element.
@@ -3437,20 +3440,48 @@ class IdentifierPreparer(object):
         )
 
     def quote_schema(self, schema, force=None):
-        """Conditionally quote a schema.
+        """Conditionally quote a schema name.
+
+        The name is quoted if it is a reserved word, contains quote-necessary
+        characters, or is an instance of :class:`.quoted_name` which includes
+        ``quote`` set to ``True``.
 
         Subclasses can override this to provide database-dependent
         quoting behavior for schema names.
 
-        the 'force' flag should be considered deprecated.
+        :param schema: string schema name
+        :param force: this parameter is no longer used.
+
+         .. deprecated:: 0.9
+
+            The :paramref:`.IdentifierPreparer.force` parameter is deprecated
+            and will be removed in a future release.  Quoting preference
+            is now intrinsic to the string being quoted by making use of the
+            :class:`.quoted_name` class.
 
         """
         return self.quote(schema, force)
 
     def quote(self, ident, force=None):
-        """Conditionally quote an identifier.
+        """Conditionally quote an identfier.
+
+        The identifier is quoted if it is a reserved word, contains
+        quote-necessary characters, or is an instance of
+        :class:`.quoted_name` which includes ``quote`` set to ``True``.
+
+        Subclasses can override this to provide database-dependent
+        quoting behavior for identifier names.
+
+        :param ident: string identifier
+        :param force: this parameter is no longer used.
+
+         .. deprecated:: 0.9
+
+             The :paramref:`.IdentifierPreparer.force` parameter is deprecated
+             and will be removed in a future release.  Quoting preference
+             is now intrinsic to the string being quoted by making use of the
+             :class:`.quoted_name` class.
 
-        the 'force' flag should be considered deprecated.
         """
 
         force = getattr(ident, "quote", None)
diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py
index f247fa782..47a0a0957 100644
--- a/lib/sqlalchemy/sql/ddl.py
+++ b/lib/sqlalchemy/sql/ddl.py
@@ -103,8 +103,10 @@ class DDLElement(Executable, _DDLCompiles):
 
     @util.deprecated(
         "0.7",
-        "See :class:`.DDLEvents`, as well as "
-        ":meth:`.DDLElement.execute_if`.",
+        "The :meth:`.DDLElement.execute_at` method is deprecated and will "
+        "be removed in a future release.  Please use the :class:`.DDLEvents` "
+        "listener interface in conjunction with the "
+        ":meth:`.DDLElement.execute_if` method."
     )
     def execute_at(self, event_name, target):
         """Link execution of this DDL to the DDL lifecycle of a SchemaItem.
@@ -328,8 +330,12 @@ class DDL(DDLElement):
           SQL bind parameters are not available in DDL statements.
 
         :param on:
+
           .. deprecated:: 0.7
-            See :meth:`.DDLElement.execute_if`.
+
+            The :paramref:`.DDL.on` parameter is deprecated and will be
+            removed in a future release.  Please refer to
+            :meth:`.DDLElement.execute_if`.
 
           Optional filtering criteria.  May be a string, tuple or a callable
           predicate.  If a string, it will be compared to the name of the
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 858695719..efe11494f 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -1395,58 +1395,41 @@ class TextClause(Executable, ClauseElement):
           engine-specific format.
 
         :param autocommit:
-          Deprecated.  Use .execution_options(autocommit=<True|False>)
-          to set the autocommit option.
+
+            .. deprecated:: 0.6
+
+                The :paramref:`.text.autocommit` flag is deprecated and
+                will be removed in a future release.  Please use the
+                :paramref:`.Connection.execution_options.autocommit` parameter
+                in conjunction with the :meth:`.Executable.execution_options`
+                method.
 
         :param bind:
           an optional connection or engine to be used for this text query.
 
         :param bindparams:
-          Deprecated.  A list of :func:`.bindparam` instances used to
+          A list of :func:`.bindparam` instances used to
           provide information about parameters embedded in the statement.
-          This argument now invokes the :meth:`.TextClause.bindparams`
-          method on the construct before returning it.  E.g.::
+          E.g.::
 
               stmt = text("SELECT * FROM table WHERE id=:id",
                         bindparams=[bindparam('id', value=5, type_=Integer)])
 
-          Is equivalent to::
-
-              stmt = text("SELECT * FROM table WHERE id=:id").\
-                        bindparams(bindparam('id', value=5, type_=Integer))
-
-          .. deprecated:: 0.9.0 the :meth:`.TextClause.bindparams` method
-             supersedes the ``bindparams`` argument to :func:`.text`.
+          .. deprecated:: 0.9 the :paramref:`.TextClause.bindparams` parameter
+             is deprecated and will be removed in a future release.  Please
+             refer to the :meth:`.TextClause.bindparams` method.
 
         :param typemap:
-          Deprecated.  A dictionary mapping the names of columns
-          represented in the columns clause of a ``SELECT`` statement
-          to type objects,
-          which will be used to perform post-processing on columns within
-          the result set.  This parameter now invokes the
-          :meth:`.TextClause.columns` method, which returns a
-          :class:`.TextAsFrom` construct that gains a ``.c`` collection and
-          can be embedded in other expressions.  E.g.::
+          A dictionary mapping the names of columns represented in the columns
+          clause of a ``SELECT`` statement to type objects, e.g.::
 
               stmt = text("SELECT * FROM table",
                             typemap={'id': Integer, 'name': String},
                         )
 
-          Is equivalent to::
-
-              stmt = text("SELECT * FROM table").columns(id=Integer,
-                                                         name=String)
-
-          Or alternatively::
-
-              from sqlalchemy.sql import column
-              stmt = text("SELECT * FROM table").columns(
-                                    column('id', Integer),
-                                    column('name', String)
-                                )
-
-          .. deprecated:: 0.9.0 the :meth:`.TextClause.columns` method
-             supersedes the ``typemap`` argument to :func:`.text`.
+          .. deprecated:: 0.9  The :paramref:`.TextClause.typemap` argument is
+             deprecated and will be removed in a future release.  Please
+             refer to the :meth:`.TextClause.columns` method.
 
         .. seealso::
 
@@ -3240,6 +3223,10 @@ class Over(ColumnElement):
     order_by = None
     partition_by = None
 
+    element = None
+    """The underlying expression object to which this :class:`.Over`
+    object refers towards."""
+
     def __init__(
         self, element, partition_by=None, order_by=None, range_=None, rows=None
     ):
@@ -3386,9 +3373,9 @@ class Over(ColumnElement):
         """the element referred to by this :class:`.Over`
         clause.
 
-        .. deprecated:: 1.1 the ``func`` element has been renamed to
-           ``.element``.  The two attributes are synonymous though
-           ``.func`` is read-only.
+        .. deprecated:: 1.1 the :attr:`.Over.func` member of the :class:`.Over`
+           class is deprecated and will be removed in a future release.  Please
+           refer to the :attr:`.Over.element` attribute.
 
         """
         return self.element
@@ -4140,6 +4127,7 @@ class quoted_name(util.MemoizedSlots, util.text_type):
         ):
             return value
         self = super(quoted_name, cls).__new__(cls, value)
+
         self.quote = quote
         return self
 
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index e191cff15..9aea031f9 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -756,6 +756,22 @@ class count(GenericFunction):
     r"""The ANSI COUNT aggregate function.  With no arguments,
     emits COUNT \*.
 
+    E.g.::
+
+        from sqlalchemy import func
+        from sqlalchemy import select
+        from sqlalchemy import table, column
+
+        my_table = table('some_table', column('id'))
+
+        stmt = select([func.count()]).select_from(my_table)
+
+    Executing ``stmt`` would emit::
+
+        SELECT count(*) AS count_1
+        FROM some_table
+
+
     """
     type = sqltypes.Integer
 
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 804c8bdb8..5c1bfe450 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -113,7 +113,12 @@ class SchemaItem(SchemaEventTarget, visitors.Visitable):
         return util.generic_repr(self, omit_kwarg=["info"])
 
     @property
-    @util.deprecated("0.9", "Use ``<obj>.name.quote``")
+    @util.deprecated(
+        "0.9",
+        "The :attr:`.SchemaItem.quote` attribute is deprecated and will be "
+        "removed in a future release.  Use the :attr:`.quoted_name.quote` "
+        "attribute on the ``name`` field of the target schema item to retrieve"
+        "quoted status.")
     def quote(self):
         """Return the value of the ``quote`` flag passed
         to this schema object, for those schema items which
@@ -471,7 +476,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
                     metadata._remove_table(name, schema)
 
     @property
-    @util.deprecated("0.9", "Use ``table.schema.quote``")
+    @util.deprecated(
+        "0.9",
+        "The :meth:`.SchemaItem.quote` method is deprecated and will be "
+        "removed in a future release.  Use the :attr:`.quoted_name.quote` "
+        "attribute on the ``schema`` field of the target schema item to "
+        "retrieve quoted status.")
     def quote_schema(self):
         """Return the value of the ``quote_schema`` flag passed
         to this :class:`.Table`.
@@ -2587,14 +2597,16 @@ class PassiveDefault(DefaultClause):
     """A DDL-specified DEFAULT column value.
 
     .. deprecated:: 0.6
-        :class:`.PassiveDefault` is deprecated.
-        Use :class:`.DefaultClause`.
+
+        The :class:`.PassiveDefault` class is deprecated and will be removed
+        in a future release.  Please use :class:`.DefaultClause`.
+
     """
 
     @util.deprecated(
         "0.6",
-        ":class:`.PassiveDefault` is deprecated.  "
-        "Use :class:`.DefaultClause`.",
+        ":class:`.PassiveDefault` is deprecated and will be removed in a "
+        "future release. Use :class:`.DefaultClause`.",
         False,
     )
     def __init__(self, *arg, **kw):
@@ -3736,7 +3748,10 @@ class MetaData(SchemaItem):
           Defaults to False. ``bind`` is required when this option is set.
 
           .. deprecated:: 0.8
-                Please use the :meth:`.MetaData.reflect` method.
+
+                The :paramref:`.MetaData.reflect` flag is deprecated and will
+                be removed in a future release.   Please use the
+                :meth:`.MetaData.reflect` method.
 
         :param schema:
            The default schema to use for the :class:`.Table`,
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index beba1d242..847f8852f 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -388,31 +388,19 @@ class FromClause(Selectable):
 
     @util.deprecated(
         "1.1",
-        message="``FromClause.count()`` is deprecated. Counting "
-        "rows requires that the correct column expression and "
-        "accommodations for joins, DISTINCT, etc. must be made, "
-        "otherwise results may not be what's expected. "
-        "Please use an appropriate ``func.count()`` expression "
-        "directly.",
+        message="The :meth:`.FromClause.count` method is deprecated, "
+        "and will be removed in a future release.   Please use the "
+        ":class:`.functions.count` function available from the "
+        ":attr:`.func` namespace."
     )
     @util.dependencies("sqlalchemy.sql.functions")
     def count(self, functions, whereclause=None, **params):
         """return a SELECT COUNT generated against this
         :class:`.FromClause`.
 
-        The function generates COUNT against the
-        first column in the primary key of the table, or against
-        the first column in the table overall.   Explicit use of
-        ``func.count()`` should be preferred::
-
-            row_count = conn.scalar(
-                select([func.count('*')]).select_from(table)
-            )
-
-
         .. seealso::
 
-            :data:`.func`
+            :class:`.functions.count`
 
         """
 
@@ -1007,9 +995,15 @@ class Join(FromClause):
         between the two selectables.   If there are multiple ways
         to join, or no way to join, an error is raised.
 
-        :param ignore_nonexistent_tables:  Deprecated - this
-         flag is no longer used.  Only resolution errors regarding
-         the two given tables are propagated.
+        :param ignore_nonexistent_tables:
+
+            .. deprecated::  0.9
+
+                The :paramref:`_join_condition.ignore_nonexistent_tables`
+                parameter is deprecated and will be removed in a future
+                release.  Tables outside of the two tables being handled
+                are no longer considered.
+
 
         :param a_subset: An optional expression that is a sub-component
          of ``a``.  An attempt will be made to join to just this sub-component
@@ -2030,9 +2024,11 @@ class SelectBase(HasCTE, Executable, FromClause):
     @_generative
     @util.deprecated(
         "0.6",
-        message="``autocommit()`` is deprecated. Use "
-        ":meth:`.Executable.execution_options` with the "
-        "'autocommit' flag.",
+        message="The :meth:`.SelectBase.autocommit` method is deprecated, "
+        "and will be removed in a future release.   Please use the "
+        "the :paramref:`.Connection.execution_options.autocommit` "
+        "parameter in conjunction with the "
+        ":meth:`.Executable.execution_options` method."
     )
     def autocommit(self):
         """return a new selectable with the 'autocommit' flag set to
@@ -2099,9 +2095,9 @@ class GenerativeSelect(SelectBase):
 
         if autocommit is not None:
             util.warn_deprecated(
-                "autocommit on select() is "
-                "deprecated.  Use .execution_options(a"
-                "utocommit=True)"
+                "The select.autocommit parameter is deprecated and will be "
+                "removed in a future release.  Please refer to the "
+                "Select.execution_options.autocommit` parameter."
             )
             self._execution_options = self._execution_options.union(
                 {"autocommit": autocommit}
@@ -2719,12 +2715,15 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
             FROM clause specification.
 
         :param autocommit:
-          Deprecated.  Use ``.execution_options(autocommit=<True|False>)``
-          to set the autocommit option.
 
-          .. seealso::
+            .. deprecated:: 0.6
 
-            :meth:`.Executable.execution_options`
+                The :paramref:`.select.autocommit` parameter is deprecated
+                and will be removed in a future release.  Please refer to
+                the :paramref:`.Connection.execution_options.autocommit`
+                parameter in conjunction with the the
+                :meth:`.Executable.execution_options` method in order to
+                affect the autocommit behavior for a statement.
 
         :param bind=None:
           an :class:`~.Engine` or :class:`~.Connection` instance
@@ -2765,9 +2764,12 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
           when ``True``, applies ``FOR UPDATE`` to the end of the
           resulting statement.
 
-          .. deprecated:: 0.9.0 - use
-             :meth:`.Select.with_for_update` to specify the
-             structure of the ``FOR UPDATE`` clause.
+          .. deprecated:: 0.9
+
+            The :paramref:`.select.for_update` parameter is deprecated and
+            will be removed in a future release.  Please refer to the
+            :meth:`.Select.with_for_update` to specify the
+            structure of the ``FOR UPDATE`` clause.
 
           ``for_update`` accepts various string values interpreted by
           specific backends, including:
diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 65527645b..06b9319fa 100644
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -727,11 +727,16 @@ class Float(Numeric):
 
          .. versionadded:: 0.9.0
 
-        :param \**kwargs: deprecated.  Additional arguments here are ignored
-         by the default :class:`.Float` type.  For database specific
-         floats that support additional arguments, see that dialect's
-         documentation for details, such as
-         :class:`sqlalchemy.dialects.mysql.FLOAT`.
+        :param \**kwargs:
+
+            .. deprecated:: 0.9
+
+                Additional keyword arguments are ignored by the base
+                :class:`.Float` type, and keyword arguments will no longer
+                be accepted in a future release.  For database specific floats
+                that support additional arguments, see that dialect's
+                documentation for details, such as
+                :class:`sqlalchemy.dialects.mysql.FLOAT`.
 
         """
         self.precision = precision
@@ -975,7 +980,12 @@ class LargeBinary(_Binary):
 
 class Binary(LargeBinary):
 
-    """Deprecated.  Renamed to LargeBinary."""
+    """.. deprecated:: 0.6
+
+            The :class:`.Binary` class is deprecated and will be removed
+            in a future relase.  Please use :class:`.LargeBinary`.
+
+    """
 
     def __init__(self, *arg, **kw):
         util.warn_deprecated(