- removed redundant declarative docs

- cleanup of metadata/foreignkey docs

2 files changed, 95 insertions, 56 deletions

diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index 37fa98d78..50f8f24e6 100644
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -1,8 +1,11 @@
 """A simple declarative layer for SQLAlchemy ORM.
 
+Synopsis
+========
+
 SQLAlchemy object-relational configuration involves the usage of Table,
 mapper(), and class objects to define the three areas of configuration.
-declarative moves these three types of configuration underneath the individual
+``declarative`` moves these three types of configuration underneath the individual
 mapped class.  Regular SQLAlchemy schema and ORM constructs are used in most
 cases::
 
@@ -12,16 +15,30 @@ cases::
 
     class SomeClass(Base):
         __tablename__ = 'some_table'
-        id = Column('id', Integer, primary_key=True)
-        name =  Column('name', String(50))
+        id = Column(Integer, primary_key=True)
+        name =  Column(String(50))
 
 Above, the ``declarative_base`` callable produces a new base class from which
 all mapped classes inherit from.  When the class definition is completed, a
 new ``Table`` and ``mapper()`` have been generated, accessible via the
 ``__table__`` and ``__mapper__`` attributes on the ``SomeClass`` class.
 
-You may omit the names from the Column definitions.  Declarative will fill
-them in for you::
+Defining Attributes
+===================
+
+:class:`~sqlalchemy.schema.Column` objects may be explicitly named, 
+including using a different name than the attribute in which they are associated.
+The column will be assigned to the :class:`~sqlalchemy.schema.Table` using the
+given name, and mapped to the class using the attribute name::
+
+    class SomeClass(Base):
+        __tablename__ = 'some_table'
+        id = Column("some_table_id", Integer, primary_key=True)
+        name = Column("name", String(50))
+    
+Otherwise, you may omit the names from the Column definitions.  
+Declarative will set the ``name`` attribute on the column when the class
+is initialized::
 
     class SomeClass(Base):
         __tablename__ = 'some_table'
@@ -29,14 +46,19 @@ them in for you::
         name = Column(String(50))
 
 Attributes may be added to the class after its construction, and they will be
-added to the underlying ``Table`` and ``mapper()`` definitions as
+added to the underlying :class:`~sqlalchemy.schema.Table` and :func:`~sqlalchemy.orm.mapper()` definitions as
 appropriate::
 
     SomeClass.data = Column('data', Unicode)
     SomeClass.related = relation(RelatedInfo)
 
-Classes which are mapped explicitly using ``mapper()`` can interact freely
-with declarative classes.
+Classes which are mapped explicitly using :func:`~sqlalchemy.orm.mapper()` can interact freely
+with declarative classes.   It is recommended, though not required, that all tables 
+share the same underlying :class:`~sqlalchemy.schema.MetaData` object, so that 
+string-configured :class:`~sqlalchemy.schema.ForeignKey` references can be resolved without issue.
+
+Association of Metadata and Engine
+==================================
 
 The ``declarative_base`` base class contains a ``MetaData`` object where newly
 defined ``Table`` objects are collected.  This is accessed via the
@@ -64,6 +86,9 @@ traditional collection of ``Table`` objects::
     mymetadata = MetaData()
     Base = declarative_base(metadata=mymetadata)
 
+Configuring Relations
+=====================
+
 Relations to other classes are done in the usual way, with the added feature
 that the class specified to ``relation()`` may be a string name.  The "class
 registry" associated with ``Base`` is used at mapper compilation time to
@@ -114,9 +139,12 @@ class after the fact::
 
     User.addresses = relation(Address, primaryjoin=Address.user_id == User.id)
 
-Synonyms are one area where ``declarative`` needs to slightly change the usual
-SQLAlchemy configurational syntax.  To define a getter/setter which proxies to
-an underlying attribute, use ``synonym`` with the ``descriptor`` argument::
+Defining Synonyms
+=================
+
+Synonyms are introduced in :ref:`synonyms`. To define a getter/setter which 
+proxies to an underlying attribute, use ``synonym`` with the 
+``descriptor`` argument::
 
     class MyClass(Base):
         __tablename__ = 'sometable'
@@ -125,7 +153,7 @@ an underlying attribute, use ``synonym`` with the ``descriptor`` argument::
 
         def _get_attr(self):
             return self._some_attr
-        def _set_attr(self, attr)
+        def _set_attr(self, attr):
             self._some_attr = attr
         attr = synonym('_attr', descriptor=property(_get_attr, _set_attr))
 
@@ -136,7 +164,8 @@ class-level expression construct::
     x.attr = "some value"
     session.query(MyClass).filter(MyClass.attr == 'some other value').all()
 
-The `synonym_for` decorator can accomplish the same task::
+For simple getters, the :func:`synonym_for` decorator can be used in conjunction
+with ``@property``::
 
     class MyClass(Base):
         __tablename__ = 'sometable'
@@ -148,7 +177,8 @@ The `synonym_for` decorator can accomplish the same task::
         def attr(self):
             return self._some_attr
 
-Similarly, `comparable_using` is a front end for the `comparable_property` ORM function::
+Similarly, :func:`comparable_using` is a front end for the :func:`~sqlalchemy.orm.comparable_property` 
+ORM function::
 
     class MyClass(Base):
         __tablename__ = 'sometable'
@@ -160,6 +190,9 @@ Similarly, `comparable_using` is a front end for the `comparable_property` ORM f
         def uc_name(self):
             return self.name.upper()
 
+Table Configuration
+===================
+
 As an alternative to ``__tablename__``, a direct ``Table`` construct may be
 used.  The ``Column`` objects, which in this case require their names, will be
 added to the mapping just like a regular mapping to a table::
@@ -173,17 +206,20 @@ added to the mapping just like a regular mapping to a table::
 Other table-based attributes include ``__table_args__``, which is
 either a dictionary as in::
 
-    class MyClass(Base)
+    class MyClass(Base):
         __tablename__ = 'sometable'
         __table_args__ = {'mysql_engine':'InnoDB'}
         
 or a dictionary-containing tuple in the form 
 ``(arg1, arg2, ..., {kwarg1:value, ...})``, as in::
 
-    class MyClass(Base)
+    class MyClass(Base):
         __tablename__ = 'sometable'
         __table_args__ = (ForeignKeyConstraint(['id'], ['remote_table.id']), {'autoload':True})
 
+Mapper Configuration
+====================
+
 Mapper arguments are specified using the ``__mapper_args__`` class variable.
 Note that the column objects declared on the class are immediately usable, as
 in this joined-table inheritance example::
@@ -470,44 +506,44 @@ def declarative_base(bind=None, metadata=None, mapper=None, cls=object,
     """Construct a base class for declarative class definitions.
 
     The new base class will be given a metaclass that invokes
-    `instrument_declarative()` upon each subclass definition, and routes
+    :func:`instrument_declarative()` upon each subclass definition, and routes
     later Column- and Mapper-related attribute assignments made on the class
-    into Table and Mapper assignments.  See the `declarative` module
-    documentation for examples.
+    into Table and Mapper assignments.  
 
-    bind
-      An optional `Connectable`, will be assigned to the `metadata.bind`.
+    :param bind: An optional :class:`~sqlalchemy.engine.base.Connectable`, will be assigned 
+      the ``bind`` attribute on the :class:`~sqlalchemy.schema.MetaData` instance.
       The `engine` keyword argument is a deprecated synonym for `bind`.
 
-    metadata
-      An optional `MetaData` instance.  All Tables implicitly declared by
+    :param metadata:
+      An optional :class:`~sqlalchemy.schema.MetaData` instance.  All :class:`~sqlalchemy.schema.Table` 
+      objects implicitly declared by
       subclasses of the base will share this MetaData.  A MetaData instance
       will be create if none is provided.  The MetaData instance will be
       available via the `metadata` attribute of the generated declarative
       base class.
 
-    mapper
-      An optional callable, defaults to `sqlalchemy.orm.mapper`.  Will be
+    :param mapper:
+      An optional callable, defaults to :func:`~sqlalchemy.orm.mapper`.  Will be
       used to map subclasses to their Tables.
 
-    cls
-      Defaults to `object`.  A type to use as the base for the generated
+    :param cls:
+      Defaults to :class:`object`.  A type to use as the base for the generated
       declarative base class.  May be a type or tuple of types.
 
-    name
-      Defaults to 'Base', Python's internal display name for the generated
+    :param name:
+      Defaults to ``Base``.  The display name for the generated
       class.  Customizing this is not required, but can improve clarity in
       tracebacks and debugging.
 
-    constructor
+    :param constructor:
       Defaults to declarative._declarative_constructor, an __init__
       implementation that assigns \**kwargs for declared fields and relations
-      to an instance.  If `None` is supplied, no __init__ will be installed
+      to an instance.  If ``None`` is supplied, no __init__ will be installed
       and construction will fall back to cls.__init__ with normal Python
       semantics.
 
-    metaclass
-      Defaults to `DeclarativeMeta`.  A metaclass or __metaclass__
+    :param metaclass:
+      Defaults to :class:`DeclarativeMeta`.  A metaclass or __metaclass__
       compatible callable to use as the meta type of the generated
       declarative base class.
 
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index aeb7d61af..c96d8adf4 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -749,51 +749,51 @@ class Column(SchemaItem, expression.ColumnClause):
 class ForeignKey(SchemaItem):
     """Defines a column-level FOREIGN KEY constraint between two columns.
 
-    ``ForeignKey`` is specified as an argument to a ``Column`` object.
+    ``ForeignKey`` is specified as an argument to a :class:`Column` object, e.g.::
+    
+        t = Table("remote_table", metadata, 
+            Column("remote_id", ForeignKey("main_table.id"))
+        )
 
-    For a composite (multiple column) FOREIGN KEY, use a ForeignKeyConstraint
-    within the Table definition.
+    For a composite (multiple column) FOREIGN KEY, use a :class:`ForeignKeyConstraint`
+    object specified at the level of the :class:`Table`.
+    
+    Further examples of foreign key configuration are in :ref:`metadata_foreignkeys`.
 
     """
     def __init__(self, column, constraint=None, use_alter=False, name=None, onupdate=None, ondelete=None, deferrable=None, initially=None):
-        """Construct a column-level FOREIGN KEY.
+        """
+        Construct a column-level FOREIGN KEY.
 
-        column
-          A single target column for the key relationship.  A ``Column``
+        :param column: A single target column for the key relationship.  A :class:`Column`
           object or a column name as a string: ``tablename.columnname`` or
           ``schema.tablename.columnname``.
 
-        constraint
-          Optional.  A parent ``ForeignKeyConstraint`` object.  If not
-          supplied, a ``ForeignKeyConstraint`` will be automatically created
+        :param constraint: Optional.  A parent :class:`ForeignKeyConstraint` object.  If not
+          supplied, a :class:`ForeignKeyConstraint` will be automatically created
           and added to the parent table.
 
-        name
-          Optional string.  An in-database name for the key if `constraint` is
+        :param name: Optional string.  An in-database name for the key if `constraint` is
           not provided.
 
-        onupdate
-          Optional string.  If set, emit ON UPDATE <value> when issuing DDL
+        :param onupdate: Optional string.  If set, emit ON UPDATE <value> when issuing DDL
           for this constraint.  Typical values include CASCADE, DELETE and
           RESTRICT.
 
-        ondelete
-          Optional string.  If set, emit ON DELETE <value> when issuing DDL
+        :param ondelete: Optional string.  If set, emit ON DELETE <value> when issuing DDL
           for this constraint.  Typical values include CASCADE, DELETE and
           RESTRICT.
 
-        deferrable
-          Optional bool.  If set, emit DEFERRABLE or NOT DEFERRABLE when
+        :param deferrable: Optional bool.  If set, emit DEFERRABLE or NOT DEFERRABLE when
           issuing DDL for this constraint.
 
-        initially
-          Optional string.  If set, emit INITIALLY <value> when issuing DDL
+        :param initially: Optional string.  If set, emit INITIALLY <value> when issuing DDL
           for this constraint.
 
-        use_alter
-          If True, do not emit this key as part of the CREATE TABLE
+        :param use_alter: If True, do not emit this key as part of the CREATE TABLE
           definition.  Instead, use ALTER TABLE after table creation to add
           the key.  Useful for circular dependencies.
+          
         """
 
         self._colspec = column
@@ -1169,8 +1169,11 @@ class ForeignKeyConstraint(Constraint):
 
     Defines a single column or composite FOREIGN KEY ... REFERENCES
     constraint. For a no-frills, single column foreign key, adding a
-    ``ForeignKey`` to the definition of a ``Column`` is a shorthand equivalent
-    for an unnamed, single column ``ForeignKeyConstraint``.
+    :class:`ForeignKey` to the definition of a :class:`Column` is a shorthand equivalent
+    for an unnamed, single column :class:`ForeignKeyConstraint`.
+    
+    Examples of foreign key configuration are in :ref:`metadata_foreignkeys`.
+    
     """
 
     def __init__(self, columns, refcolumns, name=None, onupdate=None, ondelete=None, use_alter=False, deferrable=None, initially=None):