document the behavior of get() regarding invalid usages as per [ticket:2144]

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index b7b2eccec850651dd923f33691b9f67de63446a7..ef42e0d3ab401fc5b85cdb1d0aece72f3894bdba 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -628,12 +628,20 @@ class Query(object):
 
     def get(self, ident):
         """Return an instance of the object based on the 
-        given identifier, or None if not found.
+        given identifier, or ``None`` if not found.
 
-        The `ident` argument is a scalar or tuple of primary key column values
-        in the order of the mapper's "priamry key" setting, which
+        The ``ident`` argument is a scalar or tuple of 
+        primary key column values
+        in the order of the mapper's "primary key" setting, which
         defaults to the list of primary key columns for the 
         mapped :class:`.Table`.
+        
+        :meth:`get` returns only a single mapped instance, or
+        ``None``.  It is not intended to return rows or scalar
+        column values, therefore the :class:`.Query` must be 
+        constructed only against a single mapper or mapped class,
+        not a SQL expression or multiple entities.
+        Other usages raise an error.
 
         """