Index: /waeup/branches/ulif-rewrite/src/waeup/app.txt
===================================================================
--- /waeup/branches/ulif-rewrite/src/waeup/app.txt	(revision 3933)
+++ /waeup/branches/ulif-rewrite/src/waeup/app.txt	(revision 3933)
@@ -0,0 +1,60 @@
+waeup.app
+*********
+
+Base components for a WAeUP portal.
+
+:Test-Layer: unit
+
+The main WAeUP application object is given with `University`. It
+provides the main containers as faculties, hostels, etc.
+
+Creating `University` instances
+===============================
+
+As `University` instances make use of the Zope Component Architecture
+(ZCA), we have to setup the basic component registries, before we can
+create instances. We do this by simply grokking the whole `waeup`
+package. This way all interfaces, utilities and adapters defined in
+the package are looked up and registered with the global registries::
+
+    >>> import grok
+    >>> grok.testing.grok('waeup')
+
+Now we can import the `University` class and create an instence::
+
+    >>> from waeup.app import University
+    >>> myuniversity = University()
+    >>> myuniversity
+    <waeup.app.University object at 0x...>
+
+Instances of `University` comply with the interface
+`waeup.interfaces.IUniversity`::
+
+    >>> from zope.interface.verify import verifyClass
+    >>> from waeup.interfaces import IUniversity
+    >>> verifyClass(IUniversity, University)
+    True
+
+University attributes
+=====================
+
+Instances of University provide some attributes as described in the
+`IUniversity` interface:
+
+``name``
+   A string. The name of a university.
+
+``faculties``
+   An arbitrary object containing "faculties". In the case of
+   `University` it is a container of type
+   `waeup.interfaces.IFacultyContainer`.
+
+A freshly created instance provides these attributes::
+
+    >>> from waeup.app import University
+    >>> myuniversity = University()
+    >>> myuniversity.name
+    u'Sample University'
+
+    >>> myuniversity.faculties
+    <waeup.university.facultycontainer.FacultyContainer object at 0x...>
