- try to make this language more succinct and fix links

1 files changed, 14 insertions, 23 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 84bb15bd9..7b8254a66 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -2460,7 +2460,7 @@ class Query(object):
         (note this may consist of multiple result rows if join-loaded
         collections are present).
 
-        Calling ``first()`` results in an execution of the underlying query.
+        Calling :meth:`.Query.first` results in an execution of the underlying query.
 
         """
         if self._statement is not None:
@@ -2478,22 +2478,23 @@ class Query(object):
         Returns ``None`` if the query selects
         no rows.  Raises ``sqlalchemy.orm.exc.MultipleResultsFound``
         if multiple object identities are returned, or if multiple
-        rows are returned for a query that does not return object
-        identities.
+        rows are returned for a query that returns only scalar values
+        as opposed to full identity-mapped entities.
 
-        Note that an entity query, that is, one which selects one or
-        more mapped classes as opposed to individual column attributes,
-        may ultimately represent many rows but only one row of
-        unique entity or entities - this is a successful result for
-        `one_or_none()`.
-
-        Calling ``one_or_none()`` results in an execution of the underlying
+        Calling :meth:`.Query.one_or_none` results in an execution of the underlying
         query.
 
         .. versionadded:: 1.0.9
 
             Added :meth:`.Query.one_or_none`
 
+        .. seealso::
+
+            :meth:`.Query.first`
+
+            :meth:`.Query.one`
+
+
         """
         ret = list(self)
 
@@ -2512,20 +2513,10 @@ class Query(object):
         Raises ``sqlalchemy.orm.exc.NoResultFound`` if the query selects
         no rows.  Raises ``sqlalchemy.orm.exc.MultipleResultsFound``
         if multiple object identities are returned, or if multiple
-        rows are returned for a query that does not return object
-        identities.
-
-        Note that an entity query, that is, one which selects one or
-        more mapped classes as opposed to individual column attributes,
-        may ultimately represent many rows but only one row of
-        unique entity or entities - this is a successful result for one().
-
-        Calling ``one()`` results in an execution of the underlying query.
+        rows are returned for a query that returns only scalar values
+        as opposed to full identity-mapped entities.
 
-        .. versionchanged:: 0.6
-            ``one()`` fully fetches all results instead of applying
-            any kind of limit, so that the "unique"-ing of entities does not
-            conceal multiple object identities.
+        Calling :meth:`.one` results in an execution of the underlying query.
 
         .. seealso::