docuemnt join

diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 21c0c73afd98c0d0b8f81de03d2b0a8bac5f163b..1266cd82656d59aa3fb3f7e686bdb40b9823ca57 100644 (file)
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -144,26 +144,40 @@ def outerjoin(left, right, onclause=None):
 
 
 def join(left, right, onclause=None, isouter=False):
-    """Return a ``JOIN`` clause element (regular inner join).
+    """Produce a :class:`.Join` object, given two :class:`.FromClause`
+    expressions.
 
-    The returned object is an instance of :class:`.Join`.
+    E.g.::
 
-    Similar functionality is also available via the
-    :meth:`~.FromClause.join()` method on any
-    :class:`.FromClause`.
+        j = join(user_table, address_table, user_table.c.id == address_table.c.user_id)
+        stmt = select([user_table]).select_from(j)
+
+    would emit SQL along the lines of::
+
+        SELECT user.id, user.name FROM user
+        JOIN address ON user.id = address.user_id
+
+    Similar functionality is available given any :class:`.FromClause` object
+    (e.g. such as a :class:`.Table`) using the :meth:`.FromClause.join`
+    method.
 
     :param left: The left side of the join.
 
-    :param right: The right side of the join.
+    :param right: the right side of the join; this is any :class:`.FromClause`
+     object such as a :class:`.Table` object, and may also be a selectable-compatible
+     object such as an ORM-mapped class.
 
-    :param onclause:  Optional criterion for the ``ON`` clause, is
-      derived from foreign key relationships established between
-      left and right otherwise.
+    :param onclause: a SQL expression representing the ON clause of the
+     join.  If left at ``None``, :meth:`.FromClause.join` will attempt to
+     join the two tables based on a foreign key relationship.
 
-    To chain joins together, use the :meth:`.FromClause.join` or
-    :meth:`.FromClause.outerjoin` methods on the resulting
-    :class:`.Join` object.
+    :param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN.
+
+    .. seealso::
+
+        :meth:`.FromClause.join` - method form, based on a given left side
 
+        :class:`.Join` - the type of object produced
 
     """
     return Join(left, right, onclause, isouter)
@@ -2654,14 +2668,71 @@ class FromClause(Selectable):
         return select([self], whereclause, **params)
 
     def join(self, right, onclause=None, isouter=False):
-        """return a join of this :class:`.FromClause` against another
-        :class:`.FromClause`."""
+        """Return a :class:`.Join` from this :class:`.FromClause`
+        to another :class:`FromClause`.
+
+        E.g.::
+
+            j = user_table.join(address_table,
+                            user_table.c.id == address_table.c.user_id)
+            stmt = select([user_table]).select_from(j)
+
+        would emit SQL along the lines of::
+
+            SELECT user.id, user.name FROM user
+            JOIN address ON user.id = address.user_id
+
+        :param right: the right side of the join; this is any :class:`.FromClause`
+         object such as a :class:`.Table` object, and may also be a selectable-compatible
+         object such as an ORM-mapped class.
+
+        :param onclause: a SQL expression representing the ON clause of the
+         join.  If left at ``None``, :meth:`.FromClause.join` will attempt to
+         join the two tables based on a foreign key relationship.
+
+        :param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN.
+
+        .. seealso::
+
+            :func:`.join` - standalone function
+
+            :class:`.Join` - the type of object produced
+
+        """
+
 
         return Join(self, right, onclause, isouter)
 
     def outerjoin(self, right, onclause=None):
-        """return an outer join of this :class:`.FromClause` against another
-        :class:`.FromClause`."""
+        """Return a :class:`.Join` from this :class:`.FromClause`
+        to another :class:`FromClause`, with the "isouter" flag set to
+        True.
+
+        E.g.::
+
+            j = user_table.outerjoin(address_table,
+                            user_table.c.id == address_table.c.user_id)
+
+        The above is equivalent to::
+
+            j = user_table.join(address_table,
+                            user_table.c.id == address_table.c.user_id, isouter=True)
+
+        :param right: the right side of the join; this is any :class:`.FromClause`
+         object such as a :class:`.Table` object, and may also be a selectable-compatible
+         object such as an ORM-mapped class.
+
+        :param onclause: a SQL expression representing the ON clause of the
+         join.  If left at ``None``, :meth:`.FromClause.join` will attempt to
+         join the two tables based on a foreign key relationship.
+
+        .. seealso::
+
+            :meth:`.FromClause.join`
+
+            :class:`.Join`
+
+        """
 
         return Join(self, right, onclause, True)