docstrings for the hated fold_equivalents argument/function

2 files changed, 14 insertions, 12 deletions

diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 7eeff0660..2360efe05 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -2522,23 +2522,22 @@ class Join(FromClause):
         return sql_util.join_condition(primary, secondary)
 
     def select(self, whereclause=None, fold_equivalents=False, **kwargs):
-        """Create a ``Select`` from this ``Join``.
+        """Create a :class:`Select` from this :class:`Join`.
 
-        whereclause
-          the WHERE criterion that will be sent to the ``select()``
-          function
+        :param whereclause: the WHERE criterion that will be sent to 
+          the :func:`select()` function
 
-        fold_equivalents
-          based on the join criterion of this ``Join``, do not include
+        :param fold_equivalents: based on the join criterion of this 
+          :class:`Join`, do not include
           repeat column names in the column list of the resulting
           select, for columns that are calculated to be "equivalent"
-          based on the join criterion of this ``Join``. This will
+          based on the join criterion of this :class:`Join`. This will
           recursively apply to any joins directly nested by this one
-          as well.
+          as well.  This flag is specific to a particular use case
+          by the ORM and will be deprecated in 0.6.
 
-        \**kwargs
-          all other kwargs are sent to the underlying ``select()`` function.
-          See the ``select()`` module level function for details.
+        :param \**kwargs: all other kwargs are sent to the 
+          underlying :func:`select()` function.
 
         """
         if fold_equivalents:
diff --git a/lib/sqlalchemy/sql/util.py b/lib/sqlalchemy/sql/util.py
index a808c508d..b8ceabb74 100644
--- a/lib/sqlalchemy/sql/util.py
+++ b/lib/sqlalchemy/sql/util.py
@@ -346,7 +346,10 @@ def criterion_as_pairs(expression, consider_as_foreign_keys=None, consider_as_re
     return pairs
 
 def folded_equivalents(join, equivs=None):
-    """Returns the column list of the given Join with all equivalently-named,
+    """Return a list of uniquely named columns.
+    
+    The column list of the given Join will be narrowed 
+    down to a list of all equivalently-named,
     equated columns folded into one column, where 'equated' means they are
     equated to each other in the ON clause of this join.