almost through.

1 files changed, 67 insertions, 5 deletions

diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 5b5983858..b01d815a9 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -450,8 +450,22 @@ class Table(SchemaItem, expression.TableClause):
         
 
     def tometadata(self, metadata, schema=RETAIN_SCHEMA):
-        """Return a copy of this ``Table`` associated with a different
-        ``MetaData``."""
+        """Return a copy of this :class:`Table` associated with a different
+        :class:`MetaData`.
+        
+        E.g.::
+        
+            # create two metadata
+            meta1 = MetaData('sqlite:///querytest.db')
+            meta2 = MetaData()
+
+            # load 'users' from the sqlite engine
+            users_table = Table('users', meta1, autoload=True)
+
+            # create the same Table object for the plain metadata
+            users_table_2 = users_table.tometadata(meta2)
+        
+        """
 
         try:
             if schema is RETAIN_SCHEMA:
@@ -1243,7 +1257,23 @@ class DefaultGenerator(SchemaItem):
 class ColumnDefault(DefaultGenerator):
     """A plain default value on a column.
 
-    This could correspond to a constant, a callable function, or a SQL clause.
+    This could correspond to a constant, a callable function, 
+    or a SQL clause.
+    
+    :class:`.ColumnDefault` is generated automatically
+    whenever the ``default``, ``onupdate`` arguments of
+    :class:`.Column` are used.  A :class:`.ColumnDefault`
+    can be passed positionally as well.
+    
+    For example, the following::
+    
+        Column('foo', Integer, default=50)
+        
+    Is equivalent to::
+    
+        Column('foo', Integer, ColumnDefault(50))
+
+    
     """
 
     def __init__(self, arg, **kwargs):
@@ -1374,7 +1404,20 @@ class Sequence(DefaultGenerator):
 
 
 class FetchedValue(object):
-    """A default that takes effect on the database side."""
+    """A marker for a transparent database-side default.
+    
+    Use :class:`.FetchedValue` when the database is configured
+    to provide some automatic default for a column.
+    
+    E.g.::
+    
+        Column('foo', Integer, FetchedValue())
+    
+    Would indicate that some trigger or default generator
+    will create a new value for the ``foo`` column during an
+    INSERT.
+    
+    """
 
     def __init__(self, for_update=False):
         self.for_update = for_update
@@ -1391,7 +1434,26 @@ class FetchedValue(object):
 
 
 class DefaultClause(FetchedValue):
-    """A DDL-specified DEFAULT column value."""
+    """A DDL-specified DEFAULT column value.
+    
+    :class:`.DefaultClause` is a :class:`.FetchedValue`
+    that also generates a "DEFAULT" clause when
+    "CREATE TABLE" is emitted.
+    
+    :class:`.DefaultClause` is generated automatically
+    whenever the ``server_default``, ``server_onupdate`` arguments of
+    :class:`.Column` are used.  A :class:`.DefaultClause`
+    can be passed positionally as well.
+    
+    For example, the following::
+    
+        Column('foo', Integer, server_default="50")
+        
+    Is equivalent to::
+    
+        Column('foo', Integer, DefaultClause("50"))
+    
+    """
 
     def __init__(self, arg, for_update=False):
         util.assert_arg_type(arg, (basestring,