- worked through about 25% of mappers.rst to implement

up to date and clear explanations of things, including
as much context and description as possible

1 files changed, 21 insertions, 4 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 3f8300a09..cc6d15a74 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -54,7 +54,20 @@ def _generative(*assertions):
     return generate
 
 class Query(object):
-    """ORM-level SQL construction object."""
+    """ORM-level SQL construction object.
+    
+    :class:`.Query` is the source of all SELECT statements generated by the
+    ORM, both those formulated by end-user query operations as well as by 
+    high level internal operations such as related collection loading.  It 
+    features a generative interface whereby successive calls return a new
+    :class:`.Query` object, a copy of the former with additional 
+    criteria and options associated with it.
+    
+    :class:`.Query` objects are normally initially generated using the 
+    :meth:`~.Session.query` method of :class:`.Session`.  For a full walkthrough 
+    of :class:`.Query` usage, see the :ref:`ormtutorial_toplevel`.
+    
+    """
     
     _enable_eagerloads = True
     _enable_assertions = True
@@ -732,10 +745,14 @@ class Query(object):
         # given arg is a FROM clause
         self._setup_aliasizers(self._entities[l:])
 
-    @util.pending_deprecation("add_column() superceded by add_columns()")
+    @util.pending_deprecation("0.7", "add_column() is superceded by add_columns()", False)
     def add_column(self, column):
-        """Add a column expression to the list of result columns
-        to be returned."""
+        """Add a column expression to the list of result columns to be returned.
+        
+        Pending deprecation: :meth:`.add_column` will be superceded by 
+        :meth:`.add_columns`.
+        
+        """
         
         return self.add_columns(column)