doc edits

doc/build/core/expression_api.rst

@@ -1,3 +1,5 @@
+.. _expression_api_toplevel:
+
 SQL Statements and Expressions
 ==============================
 

doc/build/core/tutorial.rst

@@ -1187,12 +1187,14 @@ Finally, a delete.  Easy enough:
 Further Reference
 ==================
 
-API docs: :mod:`sqlalchemy.sql.expression`
+Expression Language Reference: :ref:`expression_api_toplevel`
 
-Table Metadata Reference: :ref:`metadata_toplevel`
+Database Metadata Reference: :ref:`metadata_toplevel`
 
-Engine/Connection/Execution Reference: :ref:`engines_toplevel`
+Engine Reference: :ref:`engines_toplevel`
 
-SQL Types: :ref:`types`
+Connection Reference: :ref:`connections_toplevel`
+
+Types Reference: :ref:`types_toplevel`
 
 

doc/build/orm/mapper_config.rst

@@ -1,7 +1,7 @@
-.. _mapper_config_toplevel:
-
 .. module:: sqlalchemy.orm
 
+.. _mapper_config_toplevel:
+
 Mapper Configuration
 ====================
 

doc/build/orm/relationships.rst

@@ -1,5 +1,7 @@
 .. module:: sqlalchemy.orm
 
+.. _relationship_config_toplevel:
+
 Relationship Configuration
 ==========================
 

doc/build/orm/tutorial.rst

@@ -1436,6 +1436,8 @@ Further Reference
 
 Query Reference: :ref:`query_api_toplevel`
 
-Further information on mapping setups are in :ref:`datamapping_toplevel`.
+Mapper Reference: :ref:`mapper_config_toplevel`
 
-Further information on working with Sessions: :ref:`session_toplevel`.
+Relationship Reference: :ref:`relationship_config_toplevel`
+
+Session Reference: :ref:`session_toplevel`.

lib/sqlalchemy/orm/query.py

@@ -498,7 +498,12 @@ class Query(object):
         
     @property
     def whereclause(self):
-        """The WHERE criterion for this Query."""
+        """A readonly attribute which returns the current WHERE criterion for this Query.
+        
+        This returned value is a SQL expression construct, or ``None`` if no 
+        criterion has been established.
+        
+        """
         return self._criterion
 
     @_generative()
@@ -2028,8 +2033,7 @@ class Query(object):
         Also, the ``before_delete()`` and ``after_delete()``
         :class:`~sqlalchemy.orm.interfaces.MapperExtension` methods are not
         called from this method. For a delete hook here, use the
-        ``after_bulk_delete()``
-        :class:`~sqlalchemy.orm.interfaces.MapperExtension` method.
+        :meth:`.SessionExtension.after_bulk_delete()` event hook.
 
         """
         #TODO: lots of duplication and ifs - probably needs to be 
@@ -2154,8 +2158,7 @@ class Query(object):
         Also, the ``before_update()`` and ``after_update()``
         :class:`~sqlalchemy.orm.interfaces.MapperExtension` methods are not
         called from this method. For an update hook here, use the
-        ``after_bulk_update()``
-        :class:`~sqlalchemy.orm.interfaces.SessionExtension` method.
+        :meth:`.SessionExtension.after_bulk_update()` event hook.
 
         """
 

lib/sqlalchemy/orm/session.py

@@ -106,13 +106,13 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False,
        The full resolution is described in the ``get_bind()`` method of
        ``Session``. Usage looks like::
 
-        sess = Session(binds={
+        Session = sessionmaker(binds={
             SomeMappedClass: create_engine('postgresql://engine1'),
             somemapper: create_engine('postgresql://engine2'),
             some_table: create_engine('postgresql://engine3'),
             })
 
-      Also see the ``bind_mapper()`` and ``bind_table()`` methods.
+      Also see the :meth:`.Session.bind_mapper` and :meth:`.Session.bind_table` methods.
 
     :param \class_: Specify an alternate class other than
        ``sqlalchemy.orm.session.Session`` which should be used by the returned
@@ -143,8 +143,9 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False,
        as returned by the ``query()`` method. Defaults to
        :class:`~sqlalchemy.orm.query.Query`.
 
-    :param twophase:  When ``True``, all transactions will be started using
-        :mod:`~sqlalchemy.engine_TwoPhaseTransaction`. During a ``commit()``,
+    :param twophase:  When ``True``, all transactions will be started as
+        a "two phase" transaction, i.e. using the "two phase" semantics
+        of the database in use along with an XID.  During a ``commit()``,
         after ``flush()`` has been issued for all attached databases, the
         ``prepare()`` method on each database's ``TwoPhaseTransaction`` will
         be called. This allows each database to roll back the entire

lib/sqlalchemy/sql/expression.py

@@ -3924,16 +3924,21 @@ class Select(_SelectBaseMixin, FromClause):
         return self._get_display_froms()
     
     @_generative
-    def with_hint(self, selectable, text, dialect_name=None):
+    def with_hint(self, selectable, text, dialect_name='*'):
         """Add an indexing hint for the given selectable to this
         :class:`Select`.
         
-        The text of the hint is written specific to a specific backend, and
-        typically uses Python string substitution syntax to render the name
-        of the table or alias, such as for Oracle::
+        The text of the hint is rendered in the appropriate
+        location for the database backend in use, relative
+        to the given :class:`.Table` or :class:`.Alias` passed as the
+        *selectable* argument. The dialect implementation
+        typically uses Python string substitution syntax
+        with the token ``%(name)s`` to render the name of
+        the table or alias. E.g. when using Oracle, the
+        following::
         
-            select([mytable]).with_hint(mytable, "+ index(%(name)s
-            ix_mytable)")
+            select([mytable]).\\
+                with_hint(mytable, "+ index(%(name)s ix_mytable)")
             
         Would render SQL as::
         
@@ -3943,13 +3948,11 @@ class Select(_SelectBaseMixin, FromClause):
         hint to a particular backend. Such as, to add hints for both Oracle
         and Sybase simultaneously::
         
-            select([mytable]).\
-                with_hint(mytable, "+ index(%(name)s ix_mytable)", 'oracle').\
+            select([mytable]).\\
+                with_hint(mytable, "+ index(%(name)s ix_mytable)", 'oracle').\\
                 with_hint(mytable, "WITH INDEX ix_mytable", 'sybase')
         
         """
-        if not dialect_name:
-            dialect_name = '*'
         self._hints = self._hints.union({(selectable, dialect_name):text})
         
     @property