docstring for query.correlate, [ticket:1889]

2 files changed, 25 insertions, 6 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index c33687484..18ffd108a 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -6,11 +6,11 @@
 
 """The Query class and support.
 
-Defines the :class:`~sqlalchemy.orm.query.Query` class, the central 
+Defines the :class:`.Query` class, the central 
 construct used by the ORM to construct database queries.
 
-The ``Query`` class should not be confused with the
-:class:`~sqlalchemy.sql.expression.Select` class, which defines database 
+The :class:`.Query` class should not be confused with the
+:class:`.Select` class, which defines database 
 SELECT operations at the SQL (non-ORM) level.  ``Query`` differs from 
 ``Select`` in that it returns ORM-mapped objects and interacts with an 
 ORM session, whereas the ``Select`` construct interacts directly with the 
@@ -596,6 +596,25 @@ class Query(object):
 
     @_generative()
     def correlate(self, *args):
+        """Return a :class:`.Query` construct which will correlate the given
+        FROM clauses to that of an enclosing :class:`.Query` or
+        :func:`~.expression.select`.
+        
+        The method here accepts mapped classes, :func:`.aliased` constructs,
+        and :func:`.mapper` constructs as arguments, which are resolved into
+        expression constructs, in addition to appropriate expression
+        constructs.
+        
+        The correlation arguments are ultimately passed to
+        :meth:`.Select.correlate` after coercion to expression constructs.
+        
+        The correlation arguments take effect in such cases
+        as when :meth:`.Query.from_self` is used, or when 
+        a subquery as returned by :meth:`.Query.subquery` is 
+        embedded in another :func:`~.expression.select` construct.
+        
+         """
+        
         self._correlate = self._correlate.union(
                                         _orm_selectable(s) 
                                         for s in args)
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 6f593ab48..d184816ab 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -4045,15 +4045,15 @@ class Select(_SelectBaseMixin, FromClause):
         """return a new select() construct which will correlate the given FROM
         clauses to that of an enclosing select(), if a match is found.
         
-         By "match", the given fromclause must be present in this select's
+        By "match", the given fromclause must be present in this select's
         list of FROM objects and also present in an enclosing select's list of
         FROM objects.
         
-         Calling this method turns off the select's default behavior of
+        Calling this method turns off the select's default behavior of
         "auto-correlation". Normally, select() auto-correlates all of its FROM
         clauses to those of an embedded select when compiled.
         
-         If the fromclause is None, correlation is disabled for the returned
+        If the fromclause is None, correlation is disabled for the returned
         select().
 
         """