--- a/pgtoolkit/pgmanager.py	Thu Feb 28 12:55:25 2013 +0100
+++ b/pgtoolkit/pgmanager.py	Mon Mar 04 15:39:34 2013 +0100
@@ -31,28 +31,25 @@
 
 PgManager wraps psycopg2 connect function, adding following features:
 
- * Manage database connection parameters - link connection parameters
-   to an unique identifier, retrieve connection object by this identifier
+ * Save and reuse database connection parameters
 
- * Connection pooling - connections with same identifier are pooled and reused
+ * Connection pooling
 
- * Easy query using the with statement - retrieve cursor directly by connection
-   identifier, don't worry about connections
+ * Easy query using the with statement
 
- * Dict rows - cursor has additional methods like fetchall_dict(), which
-   returns dict row instead of ordinary list-like row
+ * Dictionary rows
+
+Example usage:
 
-Example:
+    import pgmanager
 
-import pgmanager
+    pgm = pgmanager.get_instance()
+    pgm.create_conn(hostaddr='127.0.0.1', dbname='postgres')
 
-pgm = pgmanager.get_instance()
-pgm.create_conn(hostaddr='127.0.0.1', dbname='postgres')
-
-with pgm.cursor() as curs:
-    curs.execute('SELECT now() AS now')
-    row = curs.fetchone_dict()
-    print row.now
+    with pgm.cursor() as curs:
+        curs.execute('SELECT now() AS now')
+        row = curs.fetchone_dict()
+        print(row.now)
 
 First, we have obtained PgManager instance. This is like calling
 PgManager(), although in our example the instance is global. That means
@@ -67,6 +64,7 @@
 
 The row returned by fetchone_dict() is special dict object, which can be accessed
 using item or attribute access, that is row['now'] or row.now.
+
 """
 
 from contextlib import contextmanager
@@ -269,13 +267,17 @@
                     pool_size=1, dsn=None, **kwargs):
         '''Create named connection.
 
-        name -- name for connection (default is "default")
-        pool_size -- how many connections will be kept open in pool
-                     (more connections will still be created but they will be closed by put_conn)
-                     None - disable pool, always return same connection
-        isolation_level -- "autocommit", "read_committed", "serializable" or None for driver default
-        keep_alive -- set socket to keepalive mode
-        dsn -- connection string (parameters or data source name)
+        *name* -- name for connection
+
+        *pool_size* -- how many connections will be kept open in pool.
+        More connections will still be created but they will be closed by put_conn.
+        `None` will disable pool, get_conn() will then always return same connection.
+
+        *isolation_level* -- `"autocommit"`, `"read_committed"`, `"serializable"` or `None` for driver default
+
+        *keep_alive* -- set socket to keepalive mode
+
+        *dsn* -- connection string (parameters or data source name)
 
         Other keyword args are used as connection parameters.
 
@@ -299,9 +301,11 @@
         This connection can be used as usual: conn.cursor() etc.
         Don't use PgManager's cursor() and put_conn().
 
-        name -- name for connection
-        channel -- listen on this channel
-        copy_dsn -- specify name of other connection and its dsn will be used
+        *name* -- name for connection
+
+        *channel* -- listen on this channel
+
+        *copy_dsn* -- specify name of other connection and its dsn will be used
 
         Other parameters forwarded to create_conn().
 
@@ -381,8 +385,7 @@
     def put_conn(self, conn, name='default'):
         '''Put connection back to pool.
 
-        Name must be same as used for get_conn,
-        otherwise things become broken.
+        *name* must be same as used for get_conn, otherwise things become broken.
 
         '''
         self.lock.acquire()
@@ -415,7 +418,7 @@
     def cursor(self, name='default'):
         '''Cursor context.
 
-        Uses any connection of name 'name' from pool
+        Uses any connection info with *name* from pool
         and returns cursor for that connection.
 
         '''
@@ -434,13 +437,14 @@
             log_notices.info(notice.rstrip())
         conn.notices[:] = []
 
-    def wait_for_notify(self, name='default', timeout=5.0):
+    def wait_for_notify(self, name='default', timeout=None):
         '''Wait for asynchronous notifies, return the last one.
 
-        name -- name of connection, must be created using create_conn_listen()
-        timeout -- in seconds, floating point (None - wait forever)
+        *name* -- name of connection, must be created using `create_conn_listen()`
 
-        Returns None on timeout.
+        *timeout* -- in seconds, floating point (`None` means wait forever)
+
+        Returns `None` on timeout.
 
         '''
         conn = self.get_conn(name)