--- a/vregistry.py	Fri Apr 02 16:10:17 2010 +0200
+++ b/vregistry.py	Fri Apr 02 16:10:35 2010 +0200
@@ -161,11 +161,12 @@
     # dynamic selection methods ################################################
 
     def object_by_id(self, oid, *args, **kwargs):
-        """return object with the given oid. Only one object is expected to be
-        found.
+        """return object with the `oid` identifier. Only one object is expected
+        to be found.
 
-        raise `ObjectNotFound` if not object with id <oid> in <registry>
-        raise `AssertionError` if there is more than one object there
+        raise :exc:`ObjectNotFound` if not object with id <oid> in <registry>
+
+        raise :exc:`AssertionError` if there is more than one object there
         """
         objects = self[oid]
         assert len(objects) == 1, objects
@@ -175,8 +176,9 @@
         """return the most specific object among those with the given oid
         according to the given context.
 
-        raise `ObjectNotFound` if not object with id <oid> in <registry>
-        raise `NoSelectableObject` if not object apply
+        raise :exc:`ObjectNotFound` if not object with id <oid> in <registry>
+
+        raise :exc:`NoSelectableObject` if not object apply
         """
         return self._select_best(self[oid], *args, **kwargs)
 
@@ -318,6 +320,20 @@
 #         self[regname].pop(oid, None)
 
     def register_all(self, objects, modname, butclasses=()):
+        """register all `objects` given. Objects which are not from the module
+        `modname` or which are in `butclasses` won't be registered.
+
+        Typical usage is:
+
+        .. sourcecode:: python
+
+            vreg.register_all(globals().values(), __name__, (ClassIWantToRegisterExplicitly,))
+
+        So you get partially automatic registration, keeping manual registration
+        for some object (to use
+        :meth:`~cubicweb.cwvreg.CubicWebRegistry.register_and_replace` for
+        instance)
+        """
         for obj in objects:
             try:
                 if obj.__module__ != modname or obj in butclasses:
@@ -329,7 +345,13 @@
                 self.register(obj, oid=oid)
 
     def register(self, obj, registryname=None, oid=None, clear=False):
-        """base method to add an object in the registry"""
+        """register `obj` application object into `registryname` or
+        `obj.__registry__` if not specified, with identifier `oid` or
+        `obj.__regid__` if not specified.
+
+        If `clear` is true, all objects with the same identifier will be
+        previously unregistered.
+        """
         assert not '__abstract__' in obj.__dict__
         try:
             vname = obj.__name__
@@ -344,10 +366,18 @@
         self._loadedmods[obj.__module__][classid(obj)] = obj
 
     def unregister(self, obj, registryname=None):
+        """unregister `obj` application object from the registry `registryname` or
+        `obj.__registry__` if not specified.
+        """
         for registryname in class_registries(obj, registryname):
             self[registryname].unregister(obj)
 
     def register_and_replace(self, obj, replaced, registryname=None):
+        """register `obj` application object into `registryname` or
+        `obj.__registry__` if not specified. If found, the `replaced` object
+        will be unregistered first (else a warning will be issued as it's
+        generally unexpected).
+        """
         for registryname in class_registries(obj, registryname):
             self[registryname].register_and_replace(obj, replaced)