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

28 files changed, 357 insertions, 195 deletions

diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index ac427b5fd..340e12fdd 100644
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -64,8 +64,13 @@ is set to ``False`` on any integer primary key column::
 .. versionchanged::  1.3   Added ``mssql_identity_start`` and
    ``mssql_identity_increment`` parameters to :class:`.Column`.  These replace
    the use of the :class:`.Sequence` object in order to specify these values.
+
+.. deprecated:: 1.3
+
    The use of :class:`.Sequence` to specify IDENTITY characteristics is
-   deprecated and will emit a warning.
+   deprecated and will be removed in a future release.   Please use
+   the ``mssql_identity_start`` and ``mssql_identity_increment`` parameters
+   documented at :ref:`mssql_identity`.
 
 .. note::
 
diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index f738b5caf..562a7deeb 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -254,11 +254,11 @@ class Dialect(object):
     def get_primary_keys(self, connection, table_name, schema=None, **kw):
         """Return information about primary keys in `table_name`.
 
+        .. deprecated:: 0.8
 
-        Deprecated.  This method is only called by the default
-        implementation of :meth:`.Dialect.get_pk_constraint`.  Dialects should
-        instead implement the :meth:`.Dialect.get_pk_constraint` method
-        directly.
+            The :meth:`.Dialect.get_primary_keys` method is deprecated and
+            will be removed in a future release.   Please refer to the
+            :meth:`.Dialect.get_pk_constraint` method.
 
         """
 
@@ -1134,9 +1134,11 @@ class Connectable(object):
 
     @util.deprecated(
         "0.7",
-        "Use the create() method on the given schema "
-        "object directly, i.e. :meth:`.Table.create`, "
-        ":meth:`.Index.create`, :meth:`.MetaData.create_all`",
+        "The :meth:`.Connectable.create` method is deprecated and will be "
+        "removed in a future release.  Please use the ``.create()`` method "
+        "on specific schema objects to emit DDL sequences, including "
+        ":meth:`.Table.create`, :meth:`.Index.create`, and "
+        ":meth:`.MetaData.create_all`."
     )
     def create(self, entity, **kwargs):
         """Emit CREATE statements for the given schema entity.
@@ -1146,10 +1148,11 @@ class Connectable(object):
 
     @util.deprecated(
         "0.7",
-        "Use the drop() method on the given schema "
-        "object directly, i.e. :meth:`.Table.drop`, "
-        ":meth:`.Index.drop`, :meth:`.MetaData.drop_all`",
-    )
+        "The :meth:`.Connectable.drop` method is deprecated and will be "
+        "removed in a future release.  Please use the ``.drop()`` method "
+        "on specific schema objects to emit DDL sequences, including "
+        ":meth:`.Table.drop`, :meth:`.Index.drop`, and "
+        ":meth:`.MetaData.drop_all`.")
     def drop(self, entity, **kwargs):
         """Emit DROP statements for the given schema entity.
         """
diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py
index c822ff820..f2acd996d 100644
--- a/lib/sqlalchemy/engine/reflection.py
+++ b/lib/sqlalchemy/engine/reflection.py
@@ -179,10 +179,13 @@ class Inspector(object):
          resolve cycles, and will raise :class:`.CircularDependencyError`
          if cycles exist.
 
-         .. deprecated:: 1.0.0 - see
-            :meth:`.Inspector.get_sorted_table_and_fkc_names` for a version
-            of this which resolves foreign key cycles between tables
-            automatically.
+         .. deprecated:: 1.0
+
+            The :paramref:`get_table_names.order_by` parameter is deprecated
+            and will be removed in a future release.  Please refer to
+            :meth:`.Inspector.get_sorted_table_and_fkc_names` for a
+            more comprehensive solution to resolving foreign key cycles
+            between tables.
 
          .. versionchanged:: 0.8 the "foreign_key" sorting sorts tables
             in order of dependee to dependent; that is, in creation
@@ -381,8 +384,9 @@ class Inspector(object):
 
     @deprecated(
         "0.7",
-        "Call to deprecated method get_primary_keys."
-        "  Use get_pk_constraint instead.",
+        "The :meth:`.Inspector.get_primary_keys` method is deprecated and "
+        "will be removed in a future release.  Please refer to the "
+        ":meth:`.Inspector.get_pk_constraint` method."
     )
     def get_primary_keys(self, table_name, schema=None, **kw):
         """Return information about primary keys in `table_name`.
diff --git a/lib/sqlalchemy/event/api.py b/lib/sqlalchemy/event/api.py
index 4064b3e21..6a7cab057 100644
--- a/lib/sqlalchemy/event/api.py
+++ b/lib/sqlalchemy/event/api.py
@@ -34,6 +34,9 @@ def _event_key(target, identifier, fn):
 def listen(target, identifier, fn, *args, **kw):
     """Register a listener function for the given target.
 
+    The :func:`.listen` function is part of the primary interface for the
+    SQLAlchemy event system, documented at :ref:`event_toplevel`.
+
     e.g.::
 
         from sqlalchemy import event
@@ -95,6 +98,9 @@ def listen(target, identifier, fn, *args, **kw):
 def listens_for(target, identifier, *args, **kw):
     """Decorate a function as a listener for the given target + identifier.
 
+    The :func:`.listens_for` decorator is part of the primary interface for the
+    SQLAlchemy event system, documented at :ref:`event_toplevel`.
+
     e.g.::
 
         from sqlalchemy import event
diff --git a/lib/sqlalchemy/event/legacy.py b/lib/sqlalchemy/event/legacy.py
index c30b922fd..a5564e6d4 100644
--- a/lib/sqlalchemy/event/legacy.py
+++ b/lib/sqlalchemy/event/legacy.py
@@ -113,7 +113,8 @@ def _legacy_listen_examples(dispatch_collection, sample_target, fn):
     text = ""
     for since, args, conv in dispatch_collection.legacy_signatures:
         text += (
-            "\n# legacy calling style (pre-%(since)s)\n"
+            "\n# DEPRECATED calling style (pre-%(since)s, "
+            "will be removed in a future release)\n"
             "@event.listens_for(%(sample_target)s, '%(event_name)s')\n"
             "def receive_%(event_name)s("
             "%(named_event_arguments)s%(has_kw_arguments)s):\n"
@@ -132,17 +133,18 @@ def _legacy_listen_examples(dispatch_collection, sample_target, fn):
     return text
 
 
-def _version_signature_changes(dispatch_collection):
+def _version_signature_changes(parent_dispatch_cls, dispatch_collection):
     since, args, conv = dispatch_collection.legacy_signatures[0]
     return (
-        "\n.. versionchanged:: %(since)s\n"
-        "    The ``%(event_name)s`` event now accepts the \n"
+        "\n.. deprecated:: %(since)s\n"
+        "    The :class:`.%(clsname)s.%(event_name)s` event now accepts the \n"
         "    arguments ``%(named_event_arguments)s%(has_kw_arguments)s``.\n"
-        "    Listener functions which accept the previous argument \n"
-        "    signature(s) listed above will be automatically \n"
-        "    adapted to the new signature."
+        "    Support for listener functions which accept the previous \n"
+        "    argument signature(s) listed above as \"deprecated\" will be \n"
+        "    removed in a future release."
         % {
             "since": since,
+            "clsname": parent_dispatch_cls.__name__,
             "event_name": dispatch_collection.name,
             "named_event_arguments": ", ".join(dispatch_collection.arg_names),
             "has_kw_arguments": ", **kw" if dispatch_collection.has_kw else "",
@@ -168,6 +170,7 @@ def _augment_fn_docs(dispatch_collection, parent_dispatch_cls, fn):
             " " * 8,
         )
 
-        text += _version_signature_changes(dispatch_collection)
+        text += _version_signature_changes(
+            parent_dispatch_cls, dispatch_collection)
 
     return util.inject_docstring_text(fn.__doc__, text, 1)
diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py
index 01e7b454b..bfeb290a0 100644
--- a/lib/sqlalchemy/events.py
+++ b/lib/sqlalchemy/events.py
@@ -799,8 +799,10 @@ class ConnectionEvents(event.Events):
         :param exception: The **unwrapped** exception emitted directly from the
          DBAPI.  The class here is specific to the DBAPI module in use.
 
-        .. deprecated:: 0.9.7 - replaced by
-            :meth:`.ConnectionEvents.handle_error`
+        .. deprecated:: 0.9 - The :meth:`.ConnectionEvents.dbapi_error`
+           event is deprecated and will be removed in a future release.
+           Please refer to the :meth:`.ConnectionEvents.handle_error`
+           event.
 
         """
 
diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py
index bde854d24..c241aafdb 100644
--- a/lib/sqlalchemy/interfaces.py
+++ b/lib/sqlalchemy/interfaces.py
@@ -8,8 +8,12 @@
 
 """Deprecated core event interfaces.
 
-This module is **deprecated** and is superseded by the
-event system.
+
+.. deprecated:: 0.7
+    As of SQLAlchemy 0.7, the new event system described in
+    :ref:`event_toplevel` replaces the extension/proxy/listener system,
+    providing a consistent interface to all events without the need for
+    subclassing.
 
 """
 
@@ -20,10 +24,11 @@ from . import util
 class PoolListener(object):
     """Hooks into the lifecycle of connections in a :class:`.Pool`.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.PoolListener` is deprecated.   Please
-       refer to :class:`.PoolEvents`.
+       :class:`.PoolListener` is deprecated and will be removed in a future
+       release.  Please refer to :func:`.event.listen` in conjunction with
+       the :class:`.PoolEvents` listener interface.
 
     Usage::
 
@@ -156,10 +161,11 @@ class PoolListener(object):
 class ConnectionProxy(object):
     """Allows interception of statement execution by Connections.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.ConnectionProxy` is deprecated.   Please
-       refer to :class:`.ConnectionEvents`.
+       :class:`.ConnectionProxy` is deprecated and will be removed in a future
+       release.  Please refer to :func:`.event.listen` in conjunction with
+       the :class:`.ConnectionEvents` listener interface.
 
     Either or both of the ``execute()`` and ``cursor_execute()``
     may be implemented to intercept compiled statement and
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index d9f50e153..eedb89ecd 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -193,8 +193,8 @@ comparable_property = public_factory(
 
 @_sa_util.deprecated(
     "0.7",
-    message=":func:`.compile_mappers` "
-    "is renamed to :func:`.configure_mappers`",
+    message=":func:`.compile_mappers` is deprecated and will be removed "
+    "in a future release.  Please use :func:`.configure_mappers`",
 )
 def compile_mappers():
     """Initialize the inter-mapper relationships of all mappers that have
diff --git a/lib/sqlalchemy/orm/collections.py b/lib/sqlalchemy/orm/collections.py
index 2454f9fae..76d5713aa 100644
--- a/lib/sqlalchemy/orm/collections.py
+++ b/lib/sqlalchemy/orm/collections.py
@@ -428,6 +428,13 @@ class collection(object):
         return fn
 
     @staticmethod
+    @util.deprecated(
+        "1.0",
+        "The :meth:`.collection.linker` handler is deprecated and will "
+        "be removed in a future release.  Please refer to the "
+        ":meth:`.AttributeEvents.init_collection` "
+        "and :meth:`.AttributeEvents.dispose_collection` event handlers. "
+    )
     def linker(fn):
         """Tag the method as a "linked to attribute" event handler.
 
@@ -437,19 +444,27 @@ class collection(object):
         the instance.  A single argument is passed: the collection adapter
         that has been linked, or None if unlinking.
 
-        .. deprecated:: 1.0.0 - the :meth:`.collection.linker` handler
-           is superseded by the :meth:`.AttributeEvents.init_collection`
-           and :meth:`.AttributeEvents.dispose_collection` handlers.
 
         """
         fn._sa_instrument_role = "linker"
         return fn
 
     link = linker
-    """deprecated; synonym for :meth:`.collection.linker`."""
+    """Synonym for :meth:`.collection.linker`.
+
+    .. deprecated:: 1.0 - :meth:`.collection.link` is deprecated and will be
+       removed in a future release.
+
+    """
 
     @staticmethod
-    @util.deprecated("1.3", "Use the bulk_replace event handler")
+    @util.deprecated(
+        "1.3",
+        "The :meth:`.collection.converter` method is deprecated and will "
+        "be removed in a future release.  Please refer to the "
+        ":class:`.AttributeEvents.bulk_replace` listener interface in "
+        "conjunction with the :func:`.event.listen` function."
+    )
     def converter(fn):
         """Tag the method as the collection converter.
 
diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py b/lib/sqlalchemy/orm/deprecated_interfaces.py
index 0b99ce85d..619bfaba1 100644
--- a/lib/sqlalchemy/orm/deprecated_interfaces.py
+++ b/lib/sqlalchemy/orm/deprecated_interfaces.py
@@ -14,11 +14,11 @@ from .. import util
 class MapperExtension(object):
     """Base implementation for :class:`.Mapper` event hooks.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.MapperExtension` is deprecated.   Please
-       refer to :func:`.event.listen` as well as
-       :class:`.MapperEvents`.
+       :class:`.MapperExtension` is deprecated and will be removed in a future
+       release.  Please refer to :func:`.event.listen` in conjunction with
+       the :class:`.MapperEvents` listener interface.
 
     New extension classes subclass :class:`.MapperExtension` and are specified
     using the ``extension`` mapper() argument, which is a single
@@ -318,11 +318,11 @@ class SessionExtension(object):
 
     """Base implementation for :class:`.Session` event hooks.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.SessionExtension` is deprecated.   Please
-       refer to :func:`.event.listen` as well as
-       :class:`.SessionEvents`.
+       :class:`.SessionExtension` is deprecated and will be removed in a future
+       release.  Please refer to :func:`.event.listen` in conjunction with
+       the :class:`.SessionEvents` listener interface.
 
     Subclasses may be installed into a :class:`.Session` (or
     :class:`.sessionmaker`) using the ``extension`` keyword
@@ -439,11 +439,11 @@ class AttributeExtension(object):
     """Base implementation for :class:`.AttributeImpl` event hooks, events
     that fire upon attribute mutations in user code.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.AttributeExtension` is deprecated.   Please
-       refer to :func:`.event.listen` as well as
-       :class:`.AttributeEvents`.
+       :class:`.AttributeExtension` is deprecated and will be removed in a
+       future release.  Please refer to :func:`.event.listen` in conjunction
+       with the :class:`.AttributeEvents` listener interface.
 
     :class:`.AttributeExtension` is used to listen for set,
     remove, and append events on individual mapped attributes.
diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py
index 0891a2a9d..8a217e4cd 100644
--- a/lib/sqlalchemy/orm/descriptor_props.py
+++ b/lib/sqlalchemy/orm/descriptor_props.py
@@ -145,7 +145,14 @@ class CompositeProperty(DescriptorProperty):
           an :class:`.AttributeExtension` instance,
           or list of extensions, which will be prepended to the list of
           attribute listeners for the resulting descriptor placed on the
-          class.  **Deprecated.**  Please see :class:`.AttributeEvents`.
+          class.
+
+           .. deprecated:: 0.7
+
+                :class:`.AttributeExtension` is deprecated in favor of the
+                :class:`.AttributeEvents` listener interface.  The
+                :paramref:`.CompositeProperty.extension` parameter will be
+                removed in a future release.
 
         """
         super(CompositeProperty, self).__init__()
diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 7c4cfc3ba..3ad5dfa7f 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -2070,8 +2070,6 @@ class AttributeEvents(event.Events):
                 else:
                     return value
 
-
-
         .. versionadded:: 1.2
 
         :param target: the object instance receiving the event.
@@ -2279,7 +2277,7 @@ class AttributeEvents(event.Events):
 
         .. versionadded:: 1.0.0 the :meth:`.AttributeEvents.init_collection`
            and :meth:`.AttributeEvents.dispose_collection` events supersede
-           the :class:`.collection.linker` hook.
+           the :class:`.orm.collection.linker` hook.
 
         """
 
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index c0a53694a..975ffb6ab 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -270,8 +270,14 @@ class Mapper(InspectionAttr):
 
         :param extension: A :class:`.MapperExtension` instance or
            list of :class:`.MapperExtension` instances which will be applied
-           to all operations by this :class:`.Mapper`.  **Deprecated.**
-           Please see :class:`.MapperEvents`.
+           to all operations by this :class:`.Mapper`.
+
+           .. deprecated:: 0.7
+
+                :class:`.MapperExtension` is deprecated in favor of the
+                :class:`.MapperEvents` listener interface.  The
+                :paramref:`.mapper.extension` parameter will be
+                removed in a future release.
 
         :param include_properties: An inclusive list or set of string column
           names to map.
@@ -344,8 +350,9 @@ class Mapper(InspectionAttr):
            ordering.
 
            .. deprecated:: 1.1 The :paramref:`.Mapper.order_by` parameter
-              is deprecated.   Use :meth:`.Query.order_by` to determine the
-              ordering of a result set.
+              is deprecated, and will be removed in a future release.
+              Use :meth:`.Query.order_by` to determine the ordering of a
+              result set.
 
         :param passive_deletes: Indicates DELETE behavior of foreign key
            columns when a joined-table inheritance entity is being deleted.
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index 3ea68a913..700e86566 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -122,12 +122,16 @@ class ColumnProperty(StrategizedProperty):
             .. versionadded:: 0.8
 
         :param extension:
-            an
-            :class:`.AttributeExtension`
-            instance, or list of extensions, which will be prepended
-            to the list of attribute listeners for the resulting
-            descriptor placed on the class.
-            **Deprecated.** Please see :class:`.AttributeEvents`.
+            an :class:`.AttributeExtension` instance, or list of extensions,
+            which will be prepended to the list of attribute listeners for the
+            resulting descriptor placed on the class.
+
+           .. deprecated:: 0.7
+
+                :class:`.AttributeExtension` is deprecated in favor of the
+                :class:`.AttributeEvents` listener interface.   The
+                :paramref:`.ColumnProperty.extension` parameter will be
+                removed in a future release.
 
         """
         super(ColumnProperty, self).__init__()
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index a4dddcd23..775a38635 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1595,7 +1595,11 @@ class Query(object):
         """Return a new :class:`.Query` object with the specified "locking mode",
         which essentially refers to the ``FOR UPDATE`` clause.
 
-        .. deprecated:: 0.9.0 superseded by :meth:`.Query.with_for_update`.
+        .. deprecated:: 0.9
+
+            The :meth:`.Query.with_lockmode` method is deprecated and will
+            be removed in a future release.  Please refer to
+            :meth:`.Query.with_for_update`.
 
         :param mode: a string representing the desired locking mode.
          Valid values are:
@@ -1756,12 +1760,9 @@ class Query(object):
         the newly resulting ``Query``
 
         All existing ORDER BY settings can be suppressed by
-        passing ``None`` - this will suppress any ORDER BY configured
-        on mappers as well.
-
-        Alternatively, passing False will reset ORDER BY and additionally
-        re-allow default mapper.order_by to take place.   Note mapper.order_by
-        is deprecated.
+        passing ``None`` - this will suppress any ordering configured
+        on the :func:`.mapper` object using the deprecated
+        :paramref:`.mapper.order_by` parameter.
 
         """
 
diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index 27a8c4ca9..b16a72996 100644
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -411,7 +411,12 @@ class RelationshipProperty(StrategizedProperty):
           which will be prepended to the list of attribute listeners for
           the resulting descriptor placed on the class.
 
-          .. deprecated:: 0.7 Please see :class:`.AttributeEvents`.
+           .. deprecated:: 0.7
+
+                :class:`.AttributeExtension` is deprecated in favor of the
+                :class:`.AttributeEvents` listener interface. The
+                :paramref:`.RelationshipProperty.extension` parameter will be
+                removed in a future release.
 
         :param foreign_keys:
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index d226edf81..a275e44aa 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -751,10 +751,12 @@ class Session(_SessionClassMethods):
 
         :param _enable_transaction_accounting:  Defaults to ``True``.  A
            legacy-only flag which when ``False`` disables *all* 0.5-style
-           object accounting on transaction boundaries, including auto-expiry
-           of instances on rollback and commit, maintenance of the "new" and
-           "deleted" lists upon rollback, and autoflush of pending changes
-           upon :meth:`~.Session.begin`, all of which are interdependent.
+           object accounting on transaction boundaries.
+
+           .. deprecated::  0.7
+
+                the :paramref:`.Session._enable_transaction_accounting`
+                parameter will be removed in a future release.
 
         :param expire_on_commit:  Defaults to ``True``. When ``True``, all
            instances will be fully expired after each :meth:`~.commit`,
@@ -764,8 +766,14 @@ class Session(_SessionClassMethods):
         :param extension: An optional
            :class:`~.SessionExtension` instance, or a list
            of such instances, which will receive pre- and post- commit and
-           flush events, as well as a post-rollback event. **Deprecated.**
-           Please see :class:`.SessionEvents`.
+           flush events, as well as a post-rollback event.
+
+           .. deprecated:: 0.7
+
+                :class:`.SessionExtension` is deprecated in favor of the
+                :class:`.SessionEvents` listener interface.  The
+                :paramref:`.Session.extension` parameter will be
+                removed in a future release.
 
         :param info: optional dictionary of arbitrary data to be associated
            with this :class:`.Session`.  Is available via the
@@ -792,11 +800,18 @@ class Session(_SessionClassMethods):
         :param weak_identity_map:  Defaults to ``True`` - when set to
            ``False``, objects placed in the :class:`.Session` will be
            strongly referenced until explicitly removed or the
-           :class:`.Session` is closed.  **Deprecated** - The strong
-           reference identity map is legacy.  See the
-           recipe at :ref:`session_referencing_behavior` for
-           an event-based approach to maintaining strong identity
-           references.
+           :class:`.Session` is closed.
+
+           .. deprecated:: 1.0
+
+               The :paramref:`.Session.weak_identity_map` parameter as well as
+               the strong-referencing identity map are deprecated, and will be
+               removed in a future release.  For the use case where objects
+               present in a :class:`.Session` need to be automatically strong
+               referenced, see the recipe at
+               :ref:`session_referencing_behavior` for an event-based approach
+               to maintaining strong identity references.
+
 
         """
 
@@ -1757,8 +1772,9 @@ class Session(_SessionClassMethods):
 
     @util.deprecated(
         "0.7",
-        "The non-weak-referencing identity map "
-        "feature is no longer needed.",
+        "The :meth:`.Session.prune` method is deprecated along with "
+        ":paramref:`.Session.weak_identity_map`.  This method will be "
+        "removed in a future release.",
     )
     def prune(self):
         """Remove unreferenced instances cached in the identity map.
diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index 2d0716991..3aaf70013 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -821,9 +821,11 @@ See :func:`.orm.%(name)s` for usage examples.
         self._unbound_all_fn = fn
         fn.__doc__ = """Produce a standalone "all" option for :func:`.orm.%(name)s`.
 
-.. deprecated:: 0.9.0
+.. deprecated:: 0.9
 
-    The "_all()" style is replaced by method chaining, e.g.::
+    The :func:`.%(name)s_all` function is deprecated, and will be removed
+    in a future release.  Please use method chaining with :func:`.%(name)s`
+    instead, as in::
 
         session.query(MyClass).options(
             %(name)s("someattribute").%(name)s("anotherattribute")
diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index 4a1e18c1a..1f30fafec 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -1085,8 +1085,10 @@ def join(
     See :meth:`.Query.join` for information on modern usage
     of ORM level joins.
 
-    .. versionchanged:: 0.8.1 - the ``join_to_left`` parameter
-       is no longer used, and is deprecated.
+    .. deprecated:: 0.8
+
+        the ``join_to_left`` parameter is deprecated, and will be removed
+        in a future release.  The parameter has no effect.
 
     """
     return _ORMJoin(left, right, onclause, isouter, full)
diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py
index 8df0b89c6..da660c40a 100644
--- a/lib/sqlalchemy/pool/base.py
+++ b/lib/sqlalchemy/pool/base.py
@@ -170,12 +170,17 @@ class Pool(log.Identified):
          can be assigned via :func:`.create_engine` before dialect-level
          listeners are applied.
 
-        :param listeners: Deprecated.  A list of
-          :class:`~sqlalchemy.interfaces.PoolListener`-like objects or
+        :param listeners: A list of :class:`.PoolListener`-like objects or
           dictionaries of callables that receive events when DB-API
           connections are created, checked out and checked in to the
-          pool.  This has been superseded by
-          :func:`~sqlalchemy.event.listen`.
+          pool.
+
+          .. deprecated:: 0.7
+
+                :class:`.PoolListener` is deprecated in favor of the
+                :class:`.PoolEvents` listener interface.  The
+                :paramref:`.Pool.listeners` parameter will be removed in a
+                future release.
 
         :param dialect: a :class:`.Dialect` that will handle the job
          of calling rollback(), close(), or commit() on DBAPI connections.
@@ -231,8 +236,10 @@ class Pool(log.Identified):
                 event.listen(self, target, fn)
         if listeners:
             util.warn_deprecated(
-                "The 'listeners' argument to Pool (and "
-                "create_engine()) is deprecated.  Use event.listen()."
+                "The 'listeners' argument to Pool and create_engine() is "
+                "deprecated and will be removed in a future release. "
+                "Please refer to the PoolEvents class in conjunction "
+                "with event.listen()"
             )
             for l in listeners:
                 self.add_listener(l)
@@ -283,7 +290,9 @@ class Pool(log.Identified):
             )
 
     @util.deprecated(
-        2.7, "Pool.add_listener is deprecated.  Use event.listen()"
+        "0.7", "The :meth:`.Pool.add_listener` method is deprecated and "
+        "will be removed in a future release.  Please use the "
+        ":class:`.PoolEvents` listener interface."
     )
     def add_listener(self, listener):
         """Add a :class:`.PoolListener`-like object to this pool.
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(
diff --git a/lib/sqlalchemy/testing/suite/test_reflection.py b/lib/sqlalchemy/testing/suite/test_reflection.py
index 96bd188ee..1c700e328 100644
--- a/lib/sqlalchemy/testing/suite/test_reflection.py
+++ b/lib/sqlalchemy/testing/suite/test_reflection.py
@@ -584,8 +584,7 @@ class ComponentReflectionTest(fixtures.TablesTest):
         insp = Inspector(meta.bind)
         assert_raises_message(
             sa_exc.SADeprecationWarning,
-            "Call to deprecated method get_primary_keys."
-            "  Use get_pk_constraint instead.",
+            r".*get_primary_keys\(\) method is deprecated",
             insp.get_primary_keys,
             users.name,
         )