doc updates

4 files changed, 58 insertions, 10 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 7098e695d..63d76efa0 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1480,6 +1480,12 @@ class Connection(Connectable):
 class Transaction(object):
     """Represent a Transaction in progress.
 
+    The object provides :meth:`.rollback` and :meth:`.commit`
+    methods in order to control transaction boundaries.  It 
+    also implements a context manager interface so that 
+    the Python ``with`` statement can be used with the 
+    :meth:`.Connection.begin` method.
+    
     The Transaction object is **not** threadsafe.
 
     .. index::
@@ -1487,12 +1493,17 @@ class Transaction(object):
     """
 
     def __init__(self, connection, parent):
+        """The constructor for :class:`.Transaction` is private
+        and is called from within the :class:`.Connection.begin` 
+        implementation.
+        
+        """
         self.connection = connection
         self._parent = parent or self
         self.is_active = True
 
     def close(self):
-        """Close this transaction.
+        """Close this :class:`.Transaction`.
 
         If this transaction is the base transaction in a begin/commit
         nesting, the transaction will rollback().  Otherwise, the
@@ -1500,6 +1511,7 @@ class Transaction(object):
 
         This is used to cancel a Transaction without affecting the scope of
         an enclosing transaction.
+        
         """
         if not self._parent.is_active:
             return
@@ -1507,6 +1519,9 @@ class Transaction(object):
             self.rollback()
 
     def rollback(self):
+        """Roll back this :class:`.Transaction`.
+        
+        """
         if not self._parent.is_active:
             return
         self._do_rollback()
@@ -1516,6 +1531,8 @@ class Transaction(object):
         self._parent.rollback()
 
     def commit(self):
+        """Commit this :class:`.Transaction`."""
+        
         if not self._parent.is_active:
             raise exc.InvalidRequestError("This transaction is inactive")
         self._do_commit()
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index e59c5863b..4eae375d8 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -110,17 +110,19 @@ __all__ = (
 
 
 def scoped_session(session_factory, scopefunc=None):
-    """Provides thread-local management of Sessions.
+    """Provides thread-local or scoped management of :class:`.Session` objects.
 
     This is a front-end function to
-    :class:`~sqlalchemy.orm.scoping.ScopedSession`.
+    :class:`.ScopedSession`.
 
     :param session_factory: a callable function that produces
       :class:`Session` instances, such as :func:`sessionmaker`.
 
-    :param scopefunc: optional, TODO
+    :param scopefunc: Optional "scope" function which would be
+      passed to the :class:`.ScopedRegistry`.  If None, the
+      :class:`.ThreadLocalRegistry` is used by default.
 
-    :returns: an :class:`~sqlalchemy.orm.scoping.ScopedSession` instance
+    :returns: an :class:`.ScopedSession` instance
 
     Usage::
 
diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py
index af518e407..c1a5fd577 100644
--- a/lib/sqlalchemy/orm/scoping.py
+++ b/lib/sqlalchemy/orm/scoping.py
@@ -22,9 +22,13 @@ class ScopedSession(object):
 
     Usage::
 
-      Session = scoped_session(sessionmaker(autoflush=True))
+      Session = scoped_session(sessionmaker())
 
-      ... use session normally.
+    ... use Session normally.
+      
+    The internal registry is accessible as well,
+    and by default is an instance of :class:`.ThreadLocalRegistry`.
+      
 
     """
 
@@ -89,6 +93,7 @@ class ScopedSession(object):
         class when called.
 
         e.g.::
+        
             Session = scoped_session(sessionmaker())
 
             class MyClass(object):
diff --git a/lib/sqlalchemy/util.py b/lib/sqlalchemy/util.py
index b41aed8bc..10931be5e 100644
--- a/lib/sqlalchemy/util.py
+++ b/lib/sqlalchemy/util.py
@@ -1268,16 +1268,30 @@ class UniqueAppender(object):
 
 class ScopedRegistry(object):
     """A Registry that can store one or multiple instances of a single
-    class on a per-thread scoped basis, or on a customized scope.
+    class on the basis of a "scope" function.
+    
+    The object implements ``__call__`` as the "getter", so by
+    calling ``myregistry()`` the contained object is returned
+    for the current scope.
 
-    createfunc
+    :param createfunc:
       a callable that returns a new object to be placed in the registry
 
-    scopefunc
+    :param scopefunc:
       a callable that will return a key to store/retrieve an object.
     """
 
     def __init__(self, createfunc, scopefunc):
+        """Construct a new :class:`.ScopedRegistry`.
+        
+        :param createfunc:  A creation function that will generate
+          a new value for the current scope, if none is present.
+          
+        :param scopefunc:  A function that returns a hashable
+          token representing the current scope (such as, current
+          thread identifier).
+        
+        """
         self.createfunc = createfunc
         self.scopefunc = scopefunc
         self.registry = {}
@@ -1290,18 +1304,28 @@ class ScopedRegistry(object):
             return self.registry.setdefault(key, self.createfunc())
 
     def has(self):
+        """Return True if an object is present in the current scope."""
+        
         return self.scopefunc() in self.registry
 
     def set(self, obj):
+        """Set the value forthe current scope."""
+        
         self.registry[self.scopefunc()] = obj
 
     def clear(self):
+        """Clear the current scope, if any."""
+        
         try:
             del self.registry[self.scopefunc()]
         except KeyError:
             pass
 
 class ThreadLocalRegistry(ScopedRegistry):
+    """A :class:`.ScopedRegistry` that uses a ``threading.local()`` 
+    variable for storage.
+    
+    """
     def __init__(self, createfunc):
         self.createfunc = createfunc
         self.registry = threading.local()