diff -r 040d3597444f -r 7644e68c4e9f entity.py
--- a/entity.py	Tue Apr 12 17:32:06 2011 +0200
+++ b/entity.py	Wed Apr 13 08:38:24 2011 +0200
@@ -252,10 +252,12 @@
 
         >>> companycls = vreg['etypes'].etype_class(('Company')
         >>> personcls = vreg['etypes'].etype_class(('Person')
-        >>> c = companycls.cw_instantiate(req.execute, name=u'Logilab')
-        >>> personcls.cw_instantiate(req.execute, firstname=u'John', lastname=u'Doe',
-        ...                          works_for=c)
+        >>> c = companycls.cw_instantiate(session.execute, name=u'Logilab')
+        >>> p = personcls.cw_instantiate(session.execute, firstname=u'John', lastname=u'Doe',
+        ...                              works_for=c)
 
+        You can also set relation where the entity has 'object' role by
+        prefixing the relation by 'reverse_'.
         """
         rql = 'INSERT %s X' % cls.__regid__
         relations = []
@@ -274,14 +276,14 @@
                 if len(value) == 1:
                     value = iter(value).next()
                 else:
+                    # prepare IN clause
                     del kwargs[attr]
                     pending_relations.append( (attr, value) )
                     continue
             if hasattr(value, 'eid'): # non final relation
                 rvar = attr.upper()
-                # XXX safer detection of object relation
-                if attr.startswith('reverse_'):
-                    relations.append('%s %s X' % (rvar, attr[len('reverse_'):]))
+                if role == 'object':
+                    relations.append('%s %s X' % (rvar, attr))
                 else:
                     relations.append('X %s %s' % (attr, rvar))
                 restriction = '%s eid %%(%s)s' % (rvar, attr)