--- a/src/pyams_utils/zodb.py	Tue Nov 15 10:43:55 2016 +0100
+++ b/src/pyams_utils/zodb.py	Fri Nov 18 15:28:54 2016 +0100
@@ -27,6 +27,7 @@
 # import packages
 from persistent import Persistent
 from pyams_utils.adapter import adapter_config
+from pyams_utils.property import DocFieldProperty
 from pyams_utils.registry import get_utilities_for
 from pyams_utils.vocabulary import vocabulary_config
 from pyramid.events import subscriber
@@ -36,13 +37,12 @@
 from zope.container.contained import Contained
 from zope.interface import implementer
 from zope.schema import getFieldNames
-from zope.schema.fieldproperty import FieldProperty
 from zope.schema.vocabulary import SimpleVocabulary, SimpleTerm
 
 
 @adapter_config(context=IPersistent, provides=IConnection)
 def get_connection(obj):
-    """An adapter which gets a ZODB connection of a persistent object.
+    """An adapter which gets a ZODB connection from a persistent object
 
     We are assuming the object has a parent if it has been created in
     this transaction.
@@ -73,35 +73,72 @@
 
 @implementer(IZEOConnection)
 class ZEOConnection(object):
-    """ZEO connection object"""
+    """ZEO connection object
+
+    This object can be used to store all settings to be able to open a ZEO connection.
+
+    Note that a ZEO connection object is a context manager, so you can use it like this:
+
+    .. code-block:: python
+
+        from pyams_utils.zodb import ZEOConnection
+
+        def my_method(zeo_settings):
+            zeo_connection = ZEOConnection()
+            zeo_connection.update(zeo_settings)
+            with zeo_connection as root:
+                # *root* is then the ZODB root object
+                # do whatever you want with ZEO connection,
+                # which is closed automatically
+    """
 
     _storage = None
     _db = None
     _connection = None
 
-    name = FieldProperty(IZEOConnection['name'])
-    server_name = FieldProperty(IZEOConnection['server_name'])
-    server_port = FieldProperty(IZEOConnection['server_port'])
-    storage = FieldProperty(IZEOConnection['storage'])
-    username = FieldProperty(IZEOConnection['username'])
-    password = FieldProperty(IZEOConnection['password'])
-    server_realm = FieldProperty(IZEOConnection['server_realm'])
-    blob_dir = FieldProperty(IZEOConnection['blob_dir'])
-    shared_blob_dir = FieldProperty(IZEOConnection['shared_blob_dir'])
+    name = DocFieldProperty(IZEOConnection['name'])
+    server_name = DocFieldProperty(IZEOConnection['server_name'])
+    server_port = DocFieldProperty(IZEOConnection['server_port'])
+    storage = DocFieldProperty(IZEOConnection['storage'])
+    username = DocFieldProperty(IZEOConnection['username'])
+    password = DocFieldProperty(IZEOConnection['password'])
+    server_realm = DocFieldProperty(IZEOConnection['server_realm'])
+    blob_dir = DocFieldProperty(IZEOConnection['blob_dir'])
+    shared_blob_dir = DocFieldProperty(IZEOConnection['shared_blob_dir'])
 
     def get_settings(self):
+        """Get mapping of all connection settings
+
+        These settings can be converted to JSON and sent to another process, for example
+        via a ØMQ connection.
+
+        :return: dict
+        """
         result = {}
         for name in getFieldNames(IZEOConnection):
             result[name] = getattr(self, name)
         return result
 
     def update(self, settings):
+        """Update connection properties with settings as *dict*
+
+        :param dict settings: typically extracted via the :py:meth:`get_settings` method from
+            another process
+        """
         names = getFieldNames(IZEOConnection)
         for key, value in settings.items():
             if key in names:
                 setattr(self, key, value)
 
     def get_connection(self, wait=False, get_storage=False):
+        """Create ZEO client connection from current settings
+
+        :param boolean wait: should connection wait until storage is ready
+        :param boolean get_storage: if *True*, the method should return a tuple containing
+            storage and DB objects; otherwise only DB object is returned
+        :return: tuple containing ZEO client storage and DB object (if *get_storage* argument is
+            set to *True*), or only DB object otherwise
+        """
         storage = ClientStorage.ClientStorage((self.server_name, self.server_port),
                                               storage=self.storage,
                                               username=self.username or '',