Improve some documentations

Change-Id: Ibcb0da3166b94aa58fa92d544c3e5cf75844546e

5 files changed, 41 insertions, 40 deletions

diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst
index 17dd85abd..fe4903650 100644
--- a/doc/build/changelog/migration_20.rst
+++ b/doc/build/changelog/migration_20.rst
@@ -1290,8 +1290,9 @@ agnostic of the ORM**.  To achieve this, the vast majority of logic from
 ORM-specific compiler plugins receive the
 :class:`_sql.Select` construct and interpret its contents in terms of an
 ORM-style query, before passing off to the core-level compiler in order to
-create a SQL string.  With the advent of the new `SQL compilation caching
-system <change_4639>`, the majority of this ORM logic is also cached.
+create a SQL string.  With the advent of the new
+`SQL compilation caching system <change_4639>`,
+the majority of this ORM logic is also cached.
 
 
 .. seealso::
@@ -1654,7 +1655,7 @@ As is the case described at :ref:`migration_20_query_from_self`, the
 
     subquery = session.query(User).filter(User.id == 5).subquery()
 
-    ua = aliased(user, subquery)
+    ua = aliased(User, subquery)
 
     user = session.query(ua).first()
 
@@ -1664,7 +1665,7 @@ Using :term:`2.0 style`::
 
     subquery = select(User).where(User.id == 5).subquery()
 
-    ua = aliased(user, subquery)
+    ua = aliased(User, subquery)
 
     user = session.execute(select(ua)).scalars().first()
 
@@ -1710,7 +1711,7 @@ while still maintaining explicitness::
 
     # statement will raise if unique() is not used, due to joinedload()
     # of a collection.  in all other cases, unique() is not needed
-    rows = session.invoke(stmt).unique().execute().all()
+    rows = session.execute(stmt).unique().execute().all()
 
 **Discussion**
 
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index 8b9b413c4..cb452ac73 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -677,7 +677,30 @@ class ResultInternal(InPlaceGenerative):
         return uniques, strategy
 
 
-class Result(ResultInternal):
+class _WithKeys(object):
+    # used mainly to share documentation on the keys method.
+    # py2k does not allow overriding the __doc__ attribute.
+    def keys(self):
+        """Return an iterable view which yields the string keys that would
+        be represented by each :class:`.Row`.
+
+        The keys can represent the labels of the columns returned by a core
+        statement or the names of the orm classes returned by an orm
+        execution.
+
+        The view also can be tested for key containment using the Python
+        ``in`` operator, which will test both for the string keys represented
+        in the view, as well as for alternate keys such as column objects.
+
+        .. versionchanged:: 1.4 a key view object is returned rather than a
+           plain list.
+
+
+        """
+        return self._metadata.keys
+
+
+class Result(_WithKeys, ResultInternal):
     """Represent a set of database results.
 
     .. versionadded:: 1.4  The :class:`.Result` object provides a completely
@@ -705,21 +728,6 @@ class Result(ResultInternal):
     def _soft_close(self, hard=False):
         raise NotImplementedError()
 
-    def keys(self):
-        """Return an iterable view which yields the string keys that would
-        be represented by each :class:`.Row`.
-
-        The view also can be tested for key containment using the Python
-        ``in`` operator, which will test both for the string keys represented
-        in the view, as well as for alternate keys such as column objects.
-
-        .. versionchanged:: 1.4 a key view object is returned rather than a
-           plain list.
-
-
-        """
-        return self._metadata.keys
-
     @_generative
     def yield_per(self, num):
         """Configure the row-fetching strategy to fetch num rows at a time.
@@ -949,7 +957,7 @@ class Result(ResultInternal):
         :paramref:`.Connection.execution_options.stream_results` execution
         option is used indicating that the driver should not pre-buffer
         results, if possible.   Not all drivers support this option and
-        the option is silently ignored for those who do.
+        the option is silently ignored for those who do not.
 
         .. versionadded:: 1.4
 
@@ -1361,7 +1369,7 @@ class ScalarResult(FilterResult):
         return self._only_one_row(True, True, False)
 
 
-class MappingResult(FilterResult):
+class MappingResult(_WithKeys, FilterResult):
     """A wrapper for a :class:`_engine.Result` that returns dictionary values
     rather than :class:`_engine.Row` values.
 
@@ -1381,21 +1389,6 @@ class MappingResult(FilterResult):
         if result._source_supports_scalars:
             self._metadata = self._metadata._reduce([0])
 
-    def keys(self):
-        """Return an iterable view which yields the string keys that would
-        be represented by each :class:`.Row`.
-
-        The view also can be tested for key containment using the Python
-        ``in`` operator, which will test both for the string keys represented
-        in the view, as well as for alternate keys such as column objects.
-
-        .. versionchanged:: 1.4 a key view object is returned rather than a
-           plain list.
-
-
-        """
-        return self._metadata.keys
-
     def unique(self, strategy=None):
         # type: () -> MappingResult
         """Apply unique filtering to the objects returned by this
diff --git a/lib/sqlalchemy/engine/row.py b/lib/sqlalchemy/engine/row.py
index fe6831e30..288f08e29 100644
--- a/lib/sqlalchemy/engine/row.py
+++ b/lib/sqlalchemy/engine/row.py
@@ -276,6 +276,10 @@ class Row(BaseRow, collections_abc.Sequence):
         """Return the list of keys as strings represented by this
         :class:`.Row`.
 
+        The keys can represent the labels of the columns returned by a core
+        statement or the names of the orm classes returned by an orm
+        execution.
+
         This method is analogous to the Python dictionary ``.keys()`` method,
         except that it returns a list, not an iterator.
 
@@ -293,6 +297,10 @@ class Row(BaseRow, collections_abc.Sequence):
         """Return a tuple of string keys as represented by this
         :class:`.Row`.
 
+        The keys can represent the labels of the columns returned by a core
+        statement or the names of the orm classes returned by an orm
+        execution.
+
         This attribute is analogous to the Python named tuple ``._fields``
         attribute.
 
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 0e7fd2fc3..0d131c086 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1019,7 +1019,6 @@ class Query(
         """
         self.load_options += {"_invoke_all_eagers": value}
 
-    # TODO: removed in 2.0, use with_parent standalone in filter
     @util.deprecated_20(
         ":meth:`_orm.Query.with_parent`",
         alternative="Use the :func:`_orm.with_parent` standalone construct.",
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index e96da0e24..50d7d1f5b 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -215,7 +215,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
 
             The autoload parameter is deprecated and will be removed in
             version 2.0.  Please use the
-            :paramref:`_schema.Table`autoload_with` parameter, passing an
+            :paramref:`_schema.Table.autoload_with` parameter, passing an
             engine or connection.
 
         .. seealso::