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

1 files changed, 35 insertions, 33 deletions

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: