Index: /waeup/branches/ulif-rewrite/src/waeup/hostel/hostelcontainer.txt
===================================================================
--- /waeup/branches/ulif-rewrite/src/waeup/hostel/hostelcontainer.txt	(revision 3941)
+++ /waeup/branches/ulif-rewrite/src/waeup/hostel/hostelcontainer.txt	(revision 3941)
@@ -0,0 +1,72 @@
+waeup.hostel.HostelContainer
+****************************
+
+Containers for hostels.
+
+:Test-Layer: unit
+
+Getting a hostel container
+==========================
+
+We can easily create `HostelContainers`::
+
+    >>> from waeup.hostel.hostelcontainer import HostelContainer
+    >>> mycontainer = HostelContainer()
+
+Another way to get a hostel container -- without importing the class
+-- is via utilities. HostelContainer instances provide the
+IHostelContainer interface::
+
+    >>> from waeup.interfaces import IHostelContainer
+    >>> IHostelContainer.providedBy(mycontainer)
+    True
+
+Also a factory(-utility) is registered, so that we can ask for a
+hostel container without importing one. To check this, we first have
+to grok the `waeup` package. This is normally done during startup::
+
+    >>> import grok
+    >>> grok.testing.grok('waeup')
+
+Now we can ask for an object providing `IHostelContainer`::
+
+    >>> from zope.component import getUtility
+    >>> getUtility(IHostelContainer)
+    <waeup.hostel.hostelcontainer.HostelContainer object at 0x...>
+
+This way we get a thing that implements IHostelContainer without
+imports or similar.
+
+We can be sure, that the full interface is supported by the
+HostelContainer class::
+
+    >>> from zope.interface.verify import verifyClass
+    >>> verifyClass(IHostelContainer, HostelContainer)
+    True
+
+
+Storing things in hostel containers
+====================================
+
+We can, of course, store things in a hostel container. But when we
+really store an object, then it must be a hostel::
+
+    >>> mycontainer.addHostel(42)
+    Traceback (most recent call last):
+    ...
+    TypeError: HostelContainers contain only IHostel instances
+
+Okay, so we have to get a hostel first::
+
+    >>> from waeup.hostel.hostel import Hostel
+    >>> myhostel = Hostel()
+
+We can add this hostel to our container::
+
+    >>> mycontainer.addHostel(myhostel)
+    '0'
+
+We get back the key, under which the hostel was stored. It will be
+some string, but there is no guarantee at all, how this key looks
+like. It might be a string of integers, a name or whatever; you cannot
+know before.
