Index: waeup/branches/ulif-rewrite/src/waeup/university/course.txt
===================================================================
--- waeup/branches/ulif-rewrite/src/waeup/university/course.txt	(revision 4361)
+++ waeup/branches/ulif-rewrite/src/waeup/university/course.txt	(revision 4362)
@@ -1,11 +1,144 @@
-Courses
-*******
+:mod:`waeup.university.course` -- Courses
+*****************************************
+
+.. module:: waeup.university.course
+
+Components that represent courses.
 
 :Test-Layer: unit
 
+Because this module makes use of components registered with the Zope
+Component Architecture (ZCA), we first have to grok the `waeup`
+package if we want to deploy it. This happens automatically in
+real-world use:
+
+    >>> import grok
+    >>> grok.testing.grok('waeup')
+
+Content Classes (models and containers)
+=======================================
+
+:class:`Course`
+---------------
+
+.. class:: Course([code=u'NA'[, title=u'Unnamed Course'[, level=None[, credits=0[, passmark=40[, semester=1]]]]]])
+
+   Create a course instance with the given parameters.
+
+   .. attribute:: grok.implements(ICourse)
+
+   All parameters are optional:
+
+     >>> from waeup.university.course import Course
+     >>> mycourse = Course()
+     >>> mycourse
+     <waeup.university.course.Course object at 0x...>
+
+   Course instances have the attributes required by the
+   :class:`waeup.interfaces.ICourse` interface:
+
+     >>> from waeup.interfaces import ICourse
+     >>> ICourse.providedBy(mycourse)
+     True
+
+     >>> from zope.interface.verify import verifyObject
+     >>> verifyObject(ICourse, mycourse)
+     True
+
+   .. attribute:: title
+
+      Each course has a title:
+
+        >>> mycourse.title
+        u'Unnamed Course'
+
+   .. attribute:: code
+
+      Each course holds a code, which might be a shortcut or
+      abbreviation of the real course name. By default the code is
+      ``NA`` (=not assigned).
+
+      This value has to be unique if used in a :class:`Department`
+      instance as it serves as a key:
+
+        >>> mycourse.code
+        u'NA'
+
+   .. attribute:: passmark
+
+      Each course holdes a passmark, which is ``40`` by default:
+
+        >>> mycourse.passmark
+        40
+
+   .. attribute:: semester
+
+      Each course holds a semester attribute which is ``1`` by
+      default:
+
+        >>> mycourse.semester
+        1
+
+   .. attribute:: credits
+
+      Each course holds the number of credits that can be
+      earned. Default is ``0``.
+
+        >>> mycourse.credits
+        0
+
+   .. attribute:: level
+
+      Courses can have a level. This attribute is not required and the
+      default value is ``None``:
+
+        >>> mycourse.level is None
+        True
+
+
+Utilities
+=========
+
+:class:`CourseFactory`
+---------------------------
+
+.. class:: CourseFactory()
+
+   .. attribute:: grok.name(u'waeup.Course')
+
+   .. attribute:: grok.implements(IFactory)
+
+   A named utility to deliver new instances of :class:`Course`
+   without the need to import the implementation before:
+
+     >>> from zope.component import createObject
+     >>> mycourse = createObject(u'waeup.Course')
+     >>> mycourse
+     <waeup.university.course.Course object at 0x...>
+
+   The factory complies with the specifications from the
+   :class:`IFactory` insterface:
+
+     >>> from zope.interface.verify import verifyClass
+     >>> from zope.component.interfaces import IFactory
+     >>> from waeup.university.course import CourseFactory
+     >>> verifyClass(IFactory, CourseFactory)
+     True
+
+   This means also, that we can get the interfaces of the created
+   object from the factory:
+
+     >>> course_factory = CourseFactory()
+     >>> course_factory.getInterfaces()
+     <implementedBy waeup.university.course.Course>
+
+Examples
+========
+
 Creating courses
-================
+----------------
 
-We can create courses:
+The simplest way to create a :class:`Course` instance is to import the
+class and calling the constructor:
 
     >>> from waeup.university.course import Course
@@ -15,11 +148,6 @@
 
 Another way to create courses is by asking for a factory called
-``waeup.Course``. Before we can do this, we have to grok the `waeup`
-package. This happens automatically in real-world use:
-
-    >>> import grok
-    >>> grok.testing.grok('waeup')
-
-Now we can create a factory without importing a class:
+``waeup.Course``. This way we can create a factory without importing a
+class:
 
     >>> from zope.component import createObject
@@ -28,67 +156,2 @@
     <waeup.university.course.Course object at 0x...>
 
-Course attributes
-==================
-
-Courses have the attributes required by the `ICourse` interface:
-
-    >>> from waeup.interfaces import ICourse
-    >>> ICourse.providedBy(mycourse)
-    True
-
-    >>> from zope.interface.verify import verifyObject
-    >>> verifyObject(ICourse, mycourse)
-    True
-
-Each of the following attributes except ``level`` is mandatory.
-
-`title`
--------
-
-Each course has a title:
-
-    >>> mycourse.title
-    u'Unnamed Course'
-
-`code`
-------
-
-Each course holds a code, which might be a shortcut or abbreviation
-of the real course name. By default the code is ``NA`` (=not assigned):
-
-    >>> mycourse.code
-    u'NA'
-
-`passmark`
-----------
-
-Each course holdes a passmark, which is 40 by default:
-
-    >>> mycourse.passmark
-    40
-
-`semester`
-----------
-
-Each course holds a semester attribute which is 1 by default:
-
-    >>> mycourse.semester
-    1
-
-`credits`
----------
-
-Each course holds the number of credits that can be earned. Default is
-0.
-
-    >>> mycourse.credits
-    0
-
-`level`
--------
-
-Courses can have a level. This attribute is not required and the
-default value is ``None``:
-
-    >>> mycourse.level is None
-    True
