Index: /main/waeup.sirp/branches/ulif-extimgstore/src/waeup/sirp/imagestorage.py
===================================================================
--- /main/waeup.sirp/branches/ulif-extimgstore/src/waeup/sirp/imagestorage.py	(revision 7015)
+++ /main/waeup.sirp/branches/ulif-extimgstore/src/waeup/sirp/imagestorage.py	(revision 7016)
@@ -233,4 +233,10 @@
 class Basket(grok.Container):
     """A basket holds a set of image files with same hash.
+
+    It is used for storing files as blobs in ZODB. Current sites do
+    not use it.
+
+    .. deprecated:: 0.2
+
     """
 
@@ -353,4 +359,8 @@
 
     def storeFile(self, fd, filename):
+        """Store contents of file addressed by `fd` under filename `filename`.
+
+        Returns the internal file id (a string) for the file stored.
+        """
         fd.seek(0)
         digest = md5digest(fd)
@@ -371,4 +381,11 @@
 
 class ImageStorageFileRetrieval(Persistent):
+    """A persistent object to retrieve files stored in ZODB.
+
+    .. deprecated:: 0.2
+
+       Since we have :class:`ExtFileStore` now we do not need this
+       class anymore.
+    """
     grok.implements(IFileRetrieval)
 
@@ -487,5 +504,10 @@
         """Get a file stored under file ID `file_id`.
 
+        Returns a file already opened for reading.
+
         If the file cannot be found ``None`` is returned.
+
+        This methods takes into account registered handlers for any
+        marker put into the file_id.
         """
         marker, filename, base, ext = self.extractMarker(file_id)
@@ -565,10 +587,35 @@
 
 class DefaultFileStoreHandler(grok.GlobalUtility):
+    """A default handler for external file store.
+
+    This handler is the fallback called by external file stores when
+    there is no or an unknown marker in the file id.
+    """
     grok.implements(IFileStoreHandler)
 
     def pathFromFileID(self, store, root, file_id):
+        """Return the root path of external file store appended by file id.
+        """
         return os.path.join(root, file_id)
 
     def createFile(self, store, root, filename, file_id, f):
+        """Infos about what to store exactly and where.
+
+        When a file should be handled by an external file storage, it
+        looks up any handlers (like this one), passes runtime infos
+        like the storage object, root path, filename, file_id, and the
+        raw file object itself.
+
+        The handler can then change the file, raise exceptions or
+        whatever and return the result.
+
+        This handler returns the input file as-is, a path returned by
+        :meth:`pathFromFileID` and an instance of
+        :class:`hurry.file.HurryFile` for further operations.
+
+        Please note: although a handler has enough infos to store the
+        file itself, it should leave that task to the calling file
+        store.
+        """
         path = self.pathFromFileID(store, root, file_id)
         return f, path, HurryFile(filename, file_id)
