Commits

Mike Bayer committed 87d5390

docstrings for the hated fold_equivalents argument/function

Comments (0)

Files changed (2)

lib/sqlalchemy/sql/expression.py

         return sql_util.join_condition(primary, secondary)
 
     def select(self, whereclause=None, fold_equivalents=False, **kwargs):
-        """Create a ``Select`` from this ``Join``.
-
-        whereclause
-          the WHERE criterion that will be sent to the ``select()``
-          function
-
-        fold_equivalents
-          based on the join criterion of this ``Join``, do not include
+        """Create a :class:`Select` from this :class:`Join`.
+
+        :param whereclause: the WHERE criterion that will be sent to 
+          the :func:`select()` function
+
+        :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.
-
-        \**kwargs
-          all other kwargs are sent to the underlying ``select()`` function.
-          See the ``select()`` module level function for details.
+          as well.  This flag is specific to a particular use case
+          by the ORM and will be deprecated in 0.6.
+
+        :param \**kwargs: all other kwargs are sent to the 
+          underlying :func:`select()` function.
 
         """
         if fold_equivalents:

lib/sqlalchemy/sql/util.py

     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.