diff -r 01d01045a2b7 -r 9049384a2bd4 src/pyams_utils/container.py
--- a/src/pyams_utils/container.py	Tue Nov 15 10:43:55 2016 +0100
+++ b/src/pyams_utils/container.py	Fri Nov 18 15:28:54 2016 +0100
@@ -28,7 +28,10 @@
 
 
 class BTreeOrderedContainer(OrderedContainer):
-    """BTree based ordered container"""
+    """BTree based ordered container
+
+    This container maintain a manual order of it's contents
+    """
 
     def __init__(self):
         self._data = OOBTree()
@@ -37,9 +40,15 @@
 
 @adapter_config(context=IContained, provides=ISublocations)
 class ContainerSublocationsAdapter(ContextAdapter):
-    """Container sub-locations adapter"""
+    """Contained object sub-locations adapter
+
+    This adapter checks for custom ISublocations interface adapters which can
+    be defined by any component to get access to inner locations, defined for
+    example via annotations.
+    """
 
     def sublocations(self):
+        """See `zope.location.interfaces.ISublocations` interface"""
         context = self.context
         # Check for adapted sub-locations first...
         registry = get_current_registry()
@@ -61,6 +70,13 @@
     argument and must return a boolean result.
 
     All sub-objects of the root will also be searched recursively.
+
+    :param object root: the parent object from which search is started
+    :param callable condition: a callable object which may return true for a given
+        object to be selected
+    :param boolean ignore_root: if *True*, the root object will not be returned, even if it matches
+        the given condition
+    :return: an iterator for all root's sub-objects matching condition
     """
     if (not ignore_root) and condition(root):
         yield root
@@ -77,6 +93,10 @@
     """Find all objects in root that provide the specified interface
 
     All sub-objects of the root will also be searched recursively.
+
+    :param object root: object; the parent object from which search is started
+    :param Interface interface: interface; an interface that sub-objects should provide
+    :return: an iterator for all root's sub-objects that provide the given interface
     """
     for match in find_objects_matching(root, interface.providedBy):
         yield match