Index: /waeup/branches/ulif-importers/src/waeup/utils/converters.txt
===================================================================
--- /waeup/branches/ulif-importers/src/waeup/utils/converters.txt	(revision 4815)
+++ /waeup/branches/ulif-importers/src/waeup/utils/converters.txt	(revision 4816)
@@ -498,5 +498,7 @@
     '1'
 
-
+A more complex (but still realistic example) for conversion of
+:mode:`zope.schema.Choice` fields follows. Here we have a special kind
+of object, the `Cave` class, and get their `name` attribute as token.
 
     >>> class Cave(object):
@@ -505,4 +507,7 @@
     >>> def tokenizer(cave):
     ...   return cave.name
+
+The tokenizer has to be registered as an Cave-to-IToken adapter to
+keep :mod:`zc.sourcefactory` happy:
 
     >>> from zc.sourcefactory.interfaces import IToken
@@ -510,4 +515,7 @@
     >>> gsm = getGlobalSiteManager()
     >>> gsm.registerAdapter(tokenizer, required=(Cave,), provided=IToken)
+
+Now we finally can create two objects of `Cave` and make a field, that
+gives the choice between these two objects:
 
     >>> obj1 = Cave()
@@ -530,4 +538,8 @@
     ...                required=True)
 
+We get a converter for this field in the usual way. The
+:meth:`waeup.utils.converters.fromString()` method will return one of
+the objects if we feed it with ``'Wilma'`` or ``'Fred'``:
+
     >>> converter = ISchemaTypeConverter(field)
     >>> result = converter.fromString('Wilma')
@@ -538,4 +550,8 @@
     (True, 'Wilma')
 
+If we use the converter the other way round, it will call the
+tokenizer above and deliver ``'Wilma'`` or ``'Fred'`` as they are the
+tokens of the objects in question:
+
     >>> converter.toString(obj2)
     'Fred'
