1 files changed, 144 insertions, 41 deletions
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 0357122b0..6520be202 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -311,14 +311,12 @@ def subquery(alias, *args, **kwargs):
     return Select(*args, **kwargs).alias(alias)
 
 def insert(table, values=None, inline=False, **kwargs):
-    """Return an :class:`.Insert` clause element.
+    """Represent an ``INSERT`` statement via the :class:`.Insert` SQL 
+    construct.
 
-    Similar functionality is available via the :meth:`~.schema.Table.insert` method on
+    Similar functionality is available via the :meth:`~.TableClause.insert` method on
     :class:`~.schema.Table`.
 
-    See also:
-
-    :ref:`coretutorial_insert_expressions` - Core Tutorial description of the :func:`.insert` construct.
 
     :param table: The table to be inserted into.
 
@@ -352,51 +350,115 @@ def insert(table, values=None, inline=False, **kwargs):
     ``INSERT`` statement's table, the statement will be correlated
     against the ``INSERT`` statement.
 
+    See also:
+
+        :ref:`coretutorial_insert_expressions` - SQL Expression Tutorial
+
+        :ref:`inserts_and_updates` - SQL Expression Tutorial
+
     """
     return Insert(table, values, inline=inline, **kwargs)
 
 def update(table, whereclause=None, values=None, inline=False, **kwargs):
-    """Return an :class:`.Update` clause element.
+    """Represent an ``UPDATE`` statement via the :class:`.Update` SQL 
+    construct.
 
-    Similar functionality is available via the :func:`update()` method on
-    :class:`~sqlalchemy.schema.Table`.
+    E.g.::
 
-    :param table: The table to be updated.
+        from sqlalchemy import update
+        
+        stmt = update(users).where(users.c.id==5).\\
+                values(name='user #5')
 
-    :param whereclause: A :class:`.ClauseElement` describing the ``WHERE``
-     condition of the ``UPDATE`` statement. Note that the
-     :meth:`~Update.where()` generative method may also be used for this.
+    Similar functionality is available via the :meth:`~.TableClause.update` method on
+    :class:`.Table`::
+    
+        
+        stmt = users.update().\\
+                    where(users.c.id==5).\\
+                    values(name='user #5')
+
+    :param table: A :class:`.Table` object representing the database
+     table to be updated.
+
+    :param whereclause: Optional SQL expression describing the ``WHERE``
+     condition of the ``UPDATE`` statement.   Modern applications
+     may prefer to use the generative :meth:`~Update.where()` 
+     method to specify the ``WHERE`` clause.
+     
+     The WHERE clause can refer to multiple tables as of version 0.7.4.
+     For databases which support this, an ``UPDATE FROM`` clause will
+     be generated, or on MySQL, a multi-table update.  The statement 
+     will fail on databases that don't have support for multi-table
+     update statements.  A SQL-standard method of referring to
+     additional tables in the WHERE clause is to use a correlated
+     subquery::
+     
+        users.update().values(name='ed').where(
+                users.c.name==select([addresses.c.email_address]).\\
+                            where(addresses.c.user_id==users.c.id).\\
+                            as_scalar()
+                )
 
     :param values:
-      A dictionary which specifies the ``SET`` conditions of the
-      ``UPDATE``, and is optional. If left as None, the ``SET``
-      conditions are determined from the bind parameters used during
-      the compile phase of the ``UPDATE`` statement.  If the bind
-      parameters also are None during the compile phase, then the
-      ``SET`` conditions will be generated from the full list of table
-      columns.  Note that the :meth:`~Update.values()` generative method may
-      also be used for this.
+      Optional dictionary which specifies the ``SET`` conditions of the
+      ``UPDATE``.  If left as ``None``, the ``SET``
+      conditions are determined from those parameters passed to the 
+      statement during the execution and/or compilation of the 
+      statement.   When compiled standalone without any parameters,
+      the ``SET`` clause generates for all columns.
+      
+      Modern applications may prefer to use the generative 
+      :meth:`.Update.values` method to set the values of the 
+      UPDATE statement.
 
     :param inline:
-      if True, SQL defaults will be compiled 'inline' into the statement
-      and not pre-executed.
+      if True, SQL defaults present on :class:`.Column` objects via 
+      the ``default`` keyword will be compiled 'inline' into the statement
+      and not pre-executed.  This means that their values will not
+      be available in the dictionary returned from 
+      :meth:`.ResultProxy.last_updated_params`.
 
-    If both `values` and compile-time bind parameters are present, the
+    If both ``values`` and compile-time bind parameters are present, the
     compile-time bind parameters override the information specified
-    within `values` on a per-key basis.
-
-    The keys within `values` can be either :class:`~sqlalchemy.schema.Column`
-    objects or their
-    string identifiers. Each key may reference one of:
-
-    * a literal data value (i.e. string, number, etc.);
-    * a Column object;
-    * a SELECT statement.
+    within ``values`` on a per-key basis.
+
+    The keys within ``values`` can be either :class:`.Column`
+    objects or their string identifiers (specifically the "key" of the
+    :class:`.Column`, normally but not necessarily equivalent to
+    its "name").  Normally, the
+    :class:`.Column` objects used here are expected to be
+    part of the target :class:`.Table` that is the table 
+    to be updated.  However when using MySQL, a multiple-table
+    UPDATE statement can refer to columns from any of
+    the tables referred to in the WHERE clause.
+    
+    The values referred to in ``values`` are typically:
+    
+    * a literal data value (i.e. string, number, etc.)
+    * a SQL expression, such as a related :class:`.Column`,
+      a scalar-returning :func:`.select` construct, 
+      etc.
+
+    When combining :func:`.select` constructs within the values
+    clause of an :func:`.update` construct,
+    the subquery represented by the :func:`.select` should be 
+    *correlated* to the parent table, that is, providing criterion
+    which links the table inside the subquery to the outer table
+    being updated::
+    
+        users.update().values(
+                name=select([addresses.c.email_address]).\\
+                        where(addresses.c.user_id==users.c.id).\\
+                        as_scalar()
+            )
 
-    If a ``SELECT`` statement is specified which references this
-    ``UPDATE`` statement's table, the statement will be correlated
-    against the ``UPDATE`` statement.
+    See also:
 
+        :ref:`inserts_and_updates` - SQL Expression 
+        Language Tutorial
+    
+    
     """
     return Update(
             table, 
@@ -406,10 +468,11 @@ def update(table, whereclause=None, values=None, inline=False, **kwargs):
             **kwargs)
 
 def delete(table, whereclause = None, **kwargs):
-    """Return a :class:`.Delete` clause element.
+    """Represent a ``DELETE`` statement via the :class:`.Delete` SQL 
+    construct.
 
-    Similar functionality is available via the :func:`delete()` method on
-    :class:`~sqlalchemy.schema.Table`.
+    Similar functionality is available via the :meth:`~.TableClause.delete` method on
+    :class:`~.schema.Table`.
 
     :param table: The table to be updated.
 
@@ -417,6 +480,10 @@ def delete(table, whereclause = None, **kwargs):
       condition of the ``UPDATE`` statement. Note that the
       :meth:`~Delete.where()` generative method may be used instead.
 
+    See also:
+    
+        :ref:`deletes` - SQL Expression Tutorial
+
     """
     return Delete(table, whereclause, **kwargs)
 
@@ -4008,18 +4075,45 @@ class TableClause(_Immutable, FromClause):
                     **params)
 
     def insert(self, values=None, inline=False, **kwargs):
-        """Generate an :func:`insert()` construct."""
+        """Generate an :func:`.insert` construct against this
+        :class:`.TableClause`.
+        
+        E.g.::
+        
+            table.insert().values(name='foo')
+        
+        See :func:`.insert` for argument and usage information.
+        
+        """
 
         return insert(self, values=values, inline=inline, **kwargs)
 
     def update(self, whereclause=None, values=None, inline=False, **kwargs):
-        """Generate an :func:`update()` construct."""
+        """Generate an :func:`.update` construct against this
+        :class:`.TableClause`.
+        
+        E.g.::
+        
+            table.update().where(table.c.id==7).values(name='foo')
+        
+        See :func:`.update` for argument and usage information.
+        
+        """
 
         return update(self, whereclause=whereclause, 
                             values=values, inline=inline, **kwargs)
 
     def delete(self, whereclause=None, **kwargs):
-        """Generate a :func:`delete()` construct."""
+        """Generate a :func:`.delete` construct against this
+        :class:`.TableClause`.
+        
+        E.g.::
+        
+            table.delete().where(table.c.id==7)
+        
+        See :func:`.delete` for argument and usage information.
+        
+        """
 
         return delete(self, whereclause, **kwargs)
 
@@ -5070,6 +5164,15 @@ class ValuesBase(UpdateBase):
 
                 users.update().where(users.c.id==5).values({users.c.name : "some name"})
 
+        See also:
+
+            :ref:`inserts_and_updates` - SQL Expression 
+            Language Tutorial
+
+            :func:`~.expression.insert` - produce an ``INSERT`` statement
+
+            :func:`~.expression.update` - produce an ``UPDATE`` statement
+        
         """
         if args:
             v = args[0]