--- a/dbapi.py	Tue Apr 20 12:35:23 2010 +0200
+++ b/dbapi.py	Tue Apr 20 14:18:35 2010 +0200
@@ -106,11 +106,50 @@
 def connect(database=None, login=None, host=None, group=None,
             cnxprops=None, setvreg=True, mulcnx=True, initlog=True, **kwargs):
     """Constructor for creating a connection to the CubicWeb repository.
-    Returns a Connection object.
+    Returns a :class:`Connection` object.
+
+    Typical usage::
+
+      cnx = connect('myinstance', login='me', password='toto')
+
+    Arguments:
+
+    :database:
+      the instance's pyro identifier.
+
+    :login:
+      the user login to use to authenticate.
+
+    :host:
+      the pyro nameserver host. Will be detected using broadcast query if
+      unspecified.
+
+    :group:
+      the instance's pyro nameserver group. You don't have to specify it unless
+      tweaked in instance's configuration.
 
-    When method is 'pyro', setvreg is True, try to deal with connections to
-    differents instances in the same process unless specified otherwise by
-    setting the mulcnx to False.
+    :cnxprops:
+      an optional :class:`ConnectionProperties` instance, allowing to specify
+      the connection method (eg in memory or pyro). A Pyro connection will be
+      established if you don't specify that argument.
+
+    :setvreg:
+      flag telling if a registry should be initialized for the connection.
+      Don't change this unless you know what you're doing.
+
+    :mulcnx:
+      Will disappear at some point. Try to deal with connections to differents
+      instances in the same process unless specified otherwise by setting this
+      flag to False. Don't change this unless you know what you're doing.
+
+    :initlog:
+      flag telling if logging should be initialized. You usually don't want
+      logging initialization when establishing the connection from a process
+      where it's already initialized.
+
+    :kwargs:
+      there goes authentication tokens. You usually have to specify for
+      instance a password for the given user, using a named 'password' argument.
     """
     config = cwconfig.CubicWebNoAppConfiguration()
     if host: