more docs

2 files changed, 68 insertions, 3 deletions

diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py
index e9763e075..ca4959e61 100644
--- a/lib/sqlalchemy/events.py
+++ b/lib/sqlalchemy/events.py
@@ -6,10 +6,47 @@ class DDLEvents(event.Events):
     """
     Define create/drop event listers for schema objects.
     
+    These events currently apply to :class:`.Table`
+    and :class:`.MetaData` objects as targets.
+    
+    e.g.::
+    
+        from sqlalchemy import event
+        from sqlalchemy import Table, Column, Metadata, Integer
+        
+        m = MetaData()
+        some_table = Table('some_table', m, Column('data', Integer))
+        
+        def on_after_create(target, connection, **kw):
+            connection.execute("ALTER TABLE %s SET name=foo_%s" % 
+                                    (target.name, target.name))
+                                    
+        event.listen(on_after_create, "on_after_create", some_table)
+    
+    DDL events integrate closely with the 
+    :class:`.DDL` class and the :class:`.DDLElement` hierarchy
+    of DDL clause constructs, which are themselves appropriate 
+    as listener callables::
+    
+        from sqlalchemy import DDL
+        event.listen(
+            DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
+            "on_after_create",
+            some_table
+        )
+    
+    The methods here define the name of an event as well
+    as the names of members that are passed to listener
+    functions.
+    
     See also:
 
         :ref:`event_toplevel`
         
+        :class:`.DDLElement`
+        
+        :class:`.DDL`
+        
         :ref:`schema_ddl_sequences`
     
     """
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index fcd9ae3f4..15b58e953 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -2196,7 +2196,34 @@ class SchemaVisitor(visitors.ClauseVisitor):
 
 
 class DDLElement(expression.Executable, expression.ClauseElement):
-    """Base class for DDL expression constructs."""
+    """Base class for DDL expression constructs.
+    
+    This class is the base for the general purpose :class:`.DDL` class,
+    as well as the various create/drop clause constructs such as
+    :class:`.CreateTable`, :class:`.DropTable`, :class:`.AddConstraint`,
+    etc.
+    
+    :class:`.DDLElement` integrates closely with SQLAlchemy events,
+    introduced in :ref:`event_toplevel`.  An instance of one is
+    itself an event receiving callable::
+    
+        event.listen(
+            AddConstraint(constraint).execute_if(dialect='postgresql'),
+            'on_after_create',
+            users
+        )
+
+    See also:
+    
+        :class:`.DDL`
+        
+        :class:`.DDLEvents`
+    
+        :ref:`event_toplevel`
+
+        :ref:`schema_ddl_sequences`
+        
+    """
     
     _execution_options = expression.Executable.\
                             _execution_options.union({'autocommit':True})
@@ -2328,7 +2355,8 @@ class DDLElement(expression.Executable, expression.ClauseElement):
         See also:
         
             :class:`.DDLEvents`
-            :mod:`sqlalchemy.event`
+            
+            :ref:`event_toplevel`
             
         """
         self.dialect = dialect
@@ -2399,7 +2427,7 @@ class DDL(DDLElement):
 
     Specifies literal SQL DDL to be executed by the database.  DDL objects 
     function as DDL event listeners, and can be subscribed to those events
-    listed in :ref:`.DDLEvents`, using either :class:`.Table` or :class:`.MetaData`
+    listed in :class:`.DDLEvents`, using either :class:`.Table` or :class:`.MetaData`
     objects as targets.   Basic templating support allows a single DDL instance 
     to handle repetitive tasks for multiple tables.