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

2 files changed, 24 insertions, 17 deletions

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