some docstrings

diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py
index 3a0e32de13c6f6ca06300cdb2695cc7e5ee0ef44..cf67abbe5093cec82ed1015d7c66a0af927c3e18 100644 (file)
--- a/lib/sqlalchemy/sql.py
+++ b/lib/sqlalchemy/sql.py
@@ -179,7 +179,25 @@ def text(text, engine=None, *args, **kwargs):
     When constructing a query from a select(), update(), insert() or delete(), using 
     plain strings for argument values will usually result in text objects being created
     automatically.  Use this function when creating textual clauses outside of other
-    ClauseElement objects, or optionally wherever plain text is to be used."""
+    ClauseElement objects, or optionally wherever plain text is to be used.
+    
+    Arguments include:
+    
+    text - the text of the SQL statement to be created.  use :<param> to specify
+    bind parameters; they will be compiled to their engine-specific format.
+    
+    engine - the engine to be used for this text query.  Alternatively, call the
+    text() method off the engine directly.
+    
+    bindparams - a list of bindparam() instances which can be used to define the
+    types and/or initial values for the bind parameters within the textual statement;
+    the keynames of the bindparams must match those within the text of the statement.
+    The types will be used for pre-processing on bind values.
+    
+    typemap - a dictionary mapping the names of columns represented in the SELECT
+    clause of the textual statement to type objects, which will be used to perform
+    post-processing on columns within the result set (for textual statements that 
+    produce result sets)."""
     return TextClause(text, engine=engine, *args, **kwargs)
 
 def null():