introductory docstring bonanza

5 files changed, 29 insertions, 13 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 783d60cf4..ff2245f39 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -5,7 +5,7 @@
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
 
-"""Basic components for SQL execution and interfacing with DB-API..
+"""Basic components for SQL execution and interfacing with DB-API.
 
 Defines the basic components used to interface DB-API modules with
 higher-level statement-construction, connection-management, execution
diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py
index 38ea903e4..b06f862f7 100644
--- a/lib/sqlalchemy/engine/default.py
+++ b/lib/sqlalchemy/engine/default.py
@@ -4,7 +4,13 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-"""Default implementations of per-dialect sqlalchemy.engine classes."""
+"""Default implementations of per-dialect sqlalchemy.engine classes.
+
+These are semi-private implementation classes which are only of importance
+to database dialect authors; dialects will usually use the classes here
+as the base class for their own corresponding classes.
+
+"""
 
 
 import re, random
diff --git a/lib/sqlalchemy/engine/strategies.py b/lib/sqlalchemy/engine/strategies.py
index 175846ff8..d4a0ad841 100644
--- a/lib/sqlalchemy/engine/strategies.py
+++ b/lib/sqlalchemy/engine/strategies.py
@@ -1,10 +1,13 @@
 """Strategies for creating new instances of Engine types.
 
-By default there are two, one which is the "thread-local" strategy,
-one which is the "plain" strategy.
-
-New strategies can be added via constructing a new EngineStrategy
-object which will add itself to the list of available strategies.
+These are semi-private implementation classes which 
+provide the underlying behavior for the "strategy" keyword argument 
+available on [sqlalchemy.engine#create_engine()].
+Current available options are ``plain``, ``threadlocal``, and
+``mock``.
+
+New strategies can be added via new ``EngineStrategy``
+classes.
 """
 
 
diff --git a/lib/sqlalchemy/engine/threadlocal.py b/lib/sqlalchemy/engine/threadlocal.py
index 6122b61b2..d07d8da83 100644
--- a/lib/sqlalchemy/engine/threadlocal.py
+++ b/lib/sqlalchemy/engine/threadlocal.py
@@ -1,12 +1,13 @@
-from sqlalchemy import util
-from sqlalchemy.engine import base
-
 """Provides a thread-local transactional wrapper around the root Engine class.
 
-Provides begin/commit methods on the engine itself which correspond to
-a thread-local transaction.
+The ``threadlocal`` module is invoked when using the ``strategy="threadlocal"`` flag
+with [sqlalchemy.engine#create_engine()].  This module is semi-private and is 
+invoked automatically when the threadlocal engine strategy is used.
 """
 
+from sqlalchemy import util
+from sqlalchemy.engine import base
+
 class TLSession(object):
     def __init__(self, engine):
         self.engine = engine
diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py
index a3487638c..663819f05 100644
--- a/lib/sqlalchemy/engine/url.py
+++ b/lib/sqlalchemy/engine/url.py
@@ -1,4 +1,10 @@
-"""Provides URL facilities for specifying database connections."""
+"""Provides the [sqlalchemy.engine.url#URL] class which encapsulates
+information about a database connection specification.
+
+The URL object is created automatically when [sqlalchemy.engine#create_engine()] is called
+with a string argument; alternatively, the URL is a public-facing construct which can
+be used directly and is also accepted directly by ``create_engine()``.
+"""
 
 import re, cgi, sys, urllib
 from sqlalchemy import exceptions