# HG changeset patch
# User Thierry Florac <thierry.florac@onf.fr>
# Date 1527240373 -7200
# Node ID 5e239a213d1d6b089fee55e67059581669d2aac4
# Parent  71a6c885b33648bc19da8e84e0eb1548b0baac25
Updated docstrings

diff -r 71a6c885b336 -r 5e239a213d1d src/pyams_utils/adapter.py
--- a/src/pyams_utils/adapter.py	Fri May 25 08:39:32 2018 +0200
+++ b/src/pyams_utils/adapter.py	Fri May 25 11:26:13 2018 +0200
@@ -76,7 +76,7 @@
 
     Annotation parameters can be:
 
-    :param str name: (default=''), name of the adapter
+    :param str='' name: name of the adapter
     :param [Interface...] context: an interface, or a tuple of interfaces, that the component adapts
     :param Interface provides: the interface that the adapter provides
     """
@@ -140,10 +140,10 @@
     :param factory: if annotations key is not found, this is the factory which will be used to
         create a new object
     :param markers: if not None, list of marker interfaces which created adapter should provide
-    :param bool notify: if 'False', no notification event will be sent on object creation
-    :param bool locate: if 'False', the new object is not attached to any parent
-    :param object parent: parent to which new object is attached
-    :param str name: if locate is not False, this is the name with which the new object is attached
+    :param bool=True notify: if 'False', no notification event will be sent on object creation
+    :param bool=True locate: if 'False', the new object is not attached to any parent
+    :param object=None parent: parent to which new object is attached
+    :param str=None name: if locate is not False, this is the name with which the new object is attached
         to it's parent.
     """
     annotations = IAnnotations(context, None)
diff -r 71a6c885b336 -r 5e239a213d1d src/pyams_utils/factory.py
--- a/src/pyams_utils/factory.py	Fri May 25 08:39:32 2018 +0200
+++ b/src/pyams_utils/factory.py	Fri May 25 11:26:13 2018 +0200
@@ -9,7 +9,6 @@
 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
 # FOR A PARTICULAR PURPOSE.
 #
-from pyams_utils.registry import get_global_registry
 
 __docformat__ = 'restructuredtext'
 
@@ -24,6 +23,7 @@
 from pyams_utils.interfaces import IObjectFactory
 
 # import packages
+from pyams_utils.registry import get_global_registry
 from zope.component import adapter, queryAdapter
 from zope.interface import implementer, Interface
 
@@ -31,7 +31,7 @@
 @adapter(Interface)
 @implementer(IObjectFactory)
 class ObjectFactoryAdapter(object):
-    """Most basic-default object factory adapter"""
+    """Most basic object factory adapter"""
 
     factory = None
 
@@ -43,12 +43,19 @@
 
 
 def get_interface_name(iface):
-    """Get interface name"""
+    """Get interface full name"""
     return iface.__module__ + '.' + iface.__name__
 
 
 def register_factory(interface, klass, registry=None, name=''):
-    """Register factory for a given interface"""
+    """Register factory for a given interface
+
+    :param interface: the interface for which the factory is registered
+    :param klass: the object factory
+    :param registry: the registry into which factory adapter should be registered; if None, the global
+        registry is used
+    :param name: custom name given to registered factory
+    """
 
     class Temp(ObjectFactoryAdapter):
         factory = klass
@@ -104,7 +111,13 @@
 
 
 def get_object_factory(interface, registry=None, name=''):
-    """Get registered factory for given interface"""
+    """Get registered factory for given interface
+
+    :param interface: the interface for which a factory is requested
+    :param registry: the registry into which registered factory should be looked for
+    :param name: name of requested factory
+    :return: the requested object factory, or None if it can't be found
+    """
     if_name = get_interface_name(interface)
     if name:
         if_name = '{0}::{1}'.format(if_name, name)
diff -r 71a6c885b336 -r 5e239a213d1d src/pyams_utils/interfaces/__init__.py
--- a/src/pyams_utils/interfaces/__init__.py	Fri May 25 08:39:32 2018 +0200
+++ b/src/pyams_utils/interfaces/__init__.py	Fri May 25 11:26:13 2018 +0200
@@ -102,8 +102,18 @@
 
 
 class IObjectFactory(Interface):
-    """Object factory interface"""
+    """Object factory interface
+
+    This interface can be used to register an "interface's object factory".
+    For a given interface, such factory can be used to get an instance of an object providing
+    this interface; several factories can be registered for the same interface if they have distinct
+    names. See :py:mod:`pyams_utils.factory` module.
+    """
 
 
 class ICacheKeyValue(Interface):
-    """Interface used to get string representation of a given object as cache key"""
+    """Interface used to get string representation of a given object as cache key
+
+    Several default adapters are given for objects (using their "id()"), strings (using string as key)
+    and for persistent objects (using their persistent OID); you are free to provide your own adapters.
+    """