3 files changed, 62 insertions, 19 deletions

diff --git a/lib/sqlalchemy/orm/base.py b/lib/sqlalchemy/orm/base.py
index 22c92b7c1..d59fac0f2 100644
--- a/lib/sqlalchemy/orm/base.py
+++ b/lib/sqlalchemy/orm/base.py
@@ -114,18 +114,38 @@ _INSTRUMENTOR = ('mapper', 'instrumentor')
 EXT_CONTINUE = util.symbol('EXT_CONTINUE')
 EXT_STOP = util.symbol('EXT_STOP')
 
-ONETOMANY = util.symbol('ONETOMANY')
-MANYTOONE = util.symbol('MANYTOONE')
-MANYTOMANY = util.symbol('MANYTOMANY')
+ONETOMANY = util.symbol('ONETOMANY',
+"""Indicates the one-to-many direction for a :func:`.relationship`.
 
-NOT_EXTENSION = util.symbol('NOT_EXTENSION')
+This symbol is typically used by the internals but may be exposed within
+certain API features.
+
+""")
+
+MANYTOONE = util.symbol('MANYTOONE',
+"""Indicates the many-to-one direction for a :func:`.relationship`.
+
+This symbol is typically used by the internals but may be exposed within
+certain API features.
+
+""")
+
+MANYTOMANY = util.symbol('MANYTOMANY',
+"""Indicates the many-to-many direction for a :func:`.relationship`.
+
+This symbol is typically used by the internals but may be exposed within
+certain API features.
+
+""")
+
+NOT_EXTENSION = util.symbol('NOT_EXTENSION',
 """Symbol indicating an :class:`_InspectionAttr` that's
    not part of sqlalchemy.ext.
 
    Is assigned to the :attr:`._InspectionAttr.extension_type`
    attibute.
 
-"""
+""")
 
 _none_set = frozenset([None])
 
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 97c160bf5..f8aaac12f 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -522,6 +522,14 @@ class Table(SchemaItem, TableClause):
 
     @property
     def key(self):
+        """Return the 'key' for this :class:`.Table`.
+
+        This value is used as the dictionary key within the
+        :attr:`.MetaData.tables` collection.   It is typically the same
+        as that of :attr:`.Table.name` for a table with no :attr:`.Table.schema`
+        set; otherwise it is typically of the form ``schemaname.tablename``.
+
+        """
         return _get_table_key(self.name, self.schema)
 
     def __repr__(self):
@@ -2719,20 +2727,11 @@ class MetaData(SchemaItem):
     execution.
 
     The :class:`.Table` objects themselves are stored in the
-    ``metadata.tables`` dictionary.
-
-    The ``bind`` property may be assigned to dynamically.  A common pattern is
-    to start unbound and then bind later when an engine is available::
+    :attr:`.MetaData.tables` dictionary.
 
-      metadata = MetaData()
-      # define tables
-      Table('mytable', metadata, ...)
-      # connect to an engine later, perhaps after loading a URL from a
-      # configuration file
-      metadata.bind = an_engine
-
-    MetaData is a thread-safe object after tables have been explicitly defined
-    or loaded via reflection.
+    :class:`.MetaData` is a thread-safe object for read operations.  Construction
+    of new tables within a single :class:`.MetaData` object, either explicitly
+    or via reflection, may not be completely thread-safe.
 
     .. seealso::
 
@@ -2788,6 +2787,20 @@ class MetaData(SchemaItem):
                     "with reflect=True")
             self.reflect()
 
+    tables = None
+    """A dictionary of :class:`.Table` objects keyed to their name or "table key".
+
+    The exact key is that determined by the :attr:`.Table.key` attribute;
+    for a table with no :attr:`.Table.schema` attribute, this is the same
+    as :attr:`.Table.name`.  For a table with a schema, it is typically of the
+    form ``schemaname.tablename``.
+
+    .. seealso::
+
+        :attr:`.MetaData.sorted_tables`
+
+    """
+
     def __repr__(self):
         return 'MetaData(bind=%r)' % self.bind
 
@@ -2889,7 +2902,9 @@ class MetaData(SchemaItem):
 
         .. seealso::
 
-            :meth:`.Inspector.sorted_tables`
+            :attr:`.MetaData.tables`
+
+            :meth:`.Inspector.get_table_names`
 
         """
         return ddl.sort_tables(self.tables.values())
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index ab8b6667c..887805aad 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -136,7 +136,15 @@ class FromClause(Selectable):
     __visit_name__ = 'fromclause'
     named_with_column = False
     _hide_froms = []
+
     schema = None
+    """Define the 'schema' attribute for this :class:`.FromClause`.
+
+    This is typically ``None`` for most objects except that of :class:`.Table`,
+    where it is taken as the value of the :paramref:`.Table.schema` argument.
+
+    """
+
     _memoized_property = util.group_expirable_memoized_property(["_columns"])
 
     @util.dependencies("sqlalchemy.sql.functions")