doc edits

3 files changed, 26 insertions, 19 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index cba3e7619..2d3f61da7 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/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.
 
         """
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index d97ef87e7..95d29812e 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/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
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 5df3b8794..ed561bbeb 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/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