doc edits

diff --git a/doc/build/core/expression_api.rst b/doc/build/core/expression_api.rst
index c01f84c2cbf0766b90d4c0716695139a7a8536d4..c39701a5966b6c802cf1d3613a089b7f67be2e0f 100644 (file)
--- a/doc/build/core/expression_api.rst
+++ b/doc/build/core/expression_api.rst
@@ -1,3 +1,5 @@
+.. _expression_api_toplevel:
+
 SQL Statements and Expressions
 ==============================
 

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 23190a143c33dde242a8b9f00370908c6ff4bdc7..bf3920198138043c4e291c613f7736d87c38d6f4 100644 (file)
--- a/doc/build/core/tutorial.rst
+++ b/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`
 
 

diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst
index 574646ca771f6163e3c2b4dd46681285fe52f500..15377436fa04afeb40dd5a5bfa5d400ce1bc66bd 100644 (file)
--- a/doc/build/orm/mapper_config.rst
+++ b/doc/build/orm/mapper_config.rst
@@ -1,7 +1,7 @@
-.. _mapper_config_toplevel:
-
 .. module:: sqlalchemy.orm
 
+.. _mapper_config_toplevel:
+
 Mapper Configuration
 ====================
 

diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst
index 34284732886658e97c5cfc41eddd352dc8d44149..f9337a5f63957e3269636773bccaf4eb714fa2ce 100644 (file)
--- a/doc/build/orm/relationships.rst
+++ b/doc/build/orm/relationships.rst
@@ -1,5 +1,7 @@
 .. module:: sqlalchemy.orm
 
+.. _relationship_config_toplevel:
+
 Relationship Configuration
 ==========================
 

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 6f38a35c90b57268c4b706db0a230fb2e2d8b9d8..1ac212961dcfb590b440c24b4903e8ba42c93d5e 100644 (file)
--- a/doc/build/orm/tutorial.rst
+++ b/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`.

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index cba3e7619ce7ec91d9a0c674b18d86749dd0f9fc..2d3f61da7e0a3a97f5e75271575465634af3fceb 100644 (file)
--- 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 d97ef87e7660fe0f54fca2a634c008e0cc532b10..95d29812e576b4df82989675c92bf94d280b86d5 100644 (file)
--- 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 5df3b879432f2d4fd186b31541b3ca3893e21174..ed561bbeb253c5c2477d1ca7b4f516cde6151bbb 100644 (file)
--- 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