--- a/dbapi.py	Fri Apr 16 12:32:52 2010 +0200
+++ b/dbapi.py	Fri Apr 16 13:22:35 2010 +0200
@@ -664,7 +664,7 @@
 # cursor object ###############################################################
 
 class Cursor(object):
-    """These objects represent a database cursor, which is used to manage the
+    """This represents a database cursor, which is used to manage the
     context of a fetch operation. Cursors created from the same connection are
     not isolated, i.e., any changes done to the database by a cursor are
     immediately visible by the other cursors. Cursors created from different
@@ -674,21 +674,18 @@
     """
 
     def __init__(self, connection, repo, req=None):
-        """This read-only attribute return a reference to the Connection
-        object on which the cursor was created.
-        """
+        # This read-only attribute returns a reference to the Connection
+        # object on which the cursor was created.
         self.connection = connection
-        """optionnal issuing request instance"""
+        # optionnal issuing request instance
         self.req = req
 
-        """This read/write attribute specifies the number of rows to fetch at a
-        time with fetchmany(). It defaults to 1 meaning to fetch a single row
-        at a time.
-
-        Implementations must observe this value with respect to the fetchmany()
-        method, but are free to interact with the database a single row at a
-        time. It may also be used in the implementation of executemany().
-        """
+        # This read/write attribute specifies the number of rows to fetch at a
+        # time with fetchmany(). It defaults to 1 meaning to fetch a single row
+        # at a time.
+        # Implementations must observe this value with respect to the fetchmany()
+        # method, but are free to interact with the database a single row at a
+        # time. It may also be used in the implementation of executemany().
         self.arraysize = 1
 
         self._repo = repo
@@ -697,7 +694,6 @@
         self._closed = None
         self._index = 0
 
-
     def close(self):
         """Close the cursor now (rather than whenever __del__ is called).  The
         cursor will be unusable from this point forward; an Error (or subclass)
@@ -867,4 +863,3 @@
         self.connection.executed_queries.append((operation, parameters,
                                                  time() - tstart, clock() - cstart))
         return rset
-

--- a/doc/book/en/development/devcore/dbapi.rst	Fri Apr 16 12:32:52 2010 +0200
+++ b/doc/book/en/development/devcore/dbapi.rst	Fri Apr 16 13:22:35 2010 +0200
@@ -1,4 +1,4 @@
-
+.. _dbapi:
 
 API Python/RQL
 ~~~~~~~~~~~~~~
@@ -13,18 +13,12 @@
 
 :rqlstring: the RQL query to execute (unicode)
 :args: if the query contains substitutions, a dictionary containing the values to use
-:cachekey:
-   an implementation detail of the RQL cache implies that if a substitution
-   is used to introduce an eid *susceptible to raise the ambiguities in the query
-   type resolution*, then we have to specify the corresponding key in the dictionary
-   through this argument
-
 
 The `Connection` object owns the methods `commit` and `rollback`. You
 *should never need to use them* during the development of the web
 interface based on the *CubicWeb* framework as it determines the end
 of the transaction depending on the query execution success. They are
-however useful in other contexts such as tests.
+however useful in other contexts such as tests or custom controllers.
 
 .. note::
   While executing update queries (SET, INSERT, DELETE), if a query generates
@@ -67,7 +61,8 @@
 
 .. sourcecode:: python
 
-   self._cw.execute('Any T WHERE T in_conf C, C name IN (%s)' % ','.join(['foo', 'bar']))
+   self._cw.execute('Any T WHERE T in_conf C, C name IN (%s)'
+                    % ','.join(['foo', 'bar']))
 
 Alternativelly, some of the common data related to an entity can be
 obtained from the `entity.related()` method (which is used under the
@@ -78,6 +73,16 @@
 
    entity.related('in_conf', 'object')
 
-Additionnaly this benefits from the fetch_attrs policy eventually
-defined on the class element, which says which attributes must be also
-loaded when the entity is loaded through the orm.
+Additionnaly this benefits from the fetch_attrs policy (see
+:ref:`FetchAttrs`) eventually defined on the class element, which says
+which attributes must be also loaded when the entity is loaded through
+the orm.
+
+
+The `Cursor` API
+~~~~~~~~~~~~~~~~
+
+The whole cursor API is developped below.
+
+.. autoclass:: cubicweb.dbapi.Cursor
+   :members: