Index: waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt
===================================================================
--- waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt	(revision 4312)
+++ waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt	(revision 4313)
@@ -1,9 +1,8 @@
-Certificates
-************
+:mod:`waeup.university.certificate` -- Certificates for WAeUP
+*************************************************************
+
+Components that represent and manage certificates.
 
 :Test-Layer: unit
-
-Creating certificates
-=====================
 
 Because certificates make use of components registered with the Zope
@@ -13,4 +12,172 @@
     >>> import grok
     >>> grok.testing.grok('waeup')
+
+
+Content Classes (models and containers)
+=======================================
+
+:class:`Certificate`
+--------------------
+
+.. class:: Certificate([code=u'NA',[ title=u'Unnamed Certificate',[ category=None,[ study_mode=None,[ start_level=None,[ end_level=None,[ application_category=None,[ m_prefix=u'',[  max_pass = u'']]]]]]]]])
+
+   Create a certificate object with the given parameters.
+
+   .. attribute:: grok.implements(ICertificate)
+
+   All parameters are optional:
+
+     >>> from waeup.university.certificate import Certificate
+     >>> mycertificate = Certificate()
+
+   Certificates have the attributes required by the `ICertificate` interface:
+
+     >>> from waeup.interfaces import ICertificate
+     >>> ICertificate.providedBy(mycertificate)
+     True
+
+     >>> from zope.interface.verify import verifyObject
+     >>> verifyObject(ICertificate, mycertificate)
+     True
+
+   .. attribute:: title
+
+      Each certificate has a title:
+
+        >>> mycertificate.title
+        u'Unnamed Certificate'
+
+   .. attribute:: code
+
+      Each certificate holds a code, which might be a shortcut or
+      abbreviation of the real certificate name. By default the code
+      is ``NA`` (=not assigned):
+
+        >>> mycertificate.code
+        u'NA'
+
+   .. attribute:: review_state
+
+      The review state can have one of the ``checking`` states defined
+      in the WAeUP workflow. These are at least the states ``checked``
+      and ``unchecked``. After a certificate is created, the review
+      state is ``unchecked``:
+
+        >>> mycertificate.review_state
+        'unchecked'
+
+      .. seealso::
+         :meth:`Certificate.check` -- mark a certificate as ``checked``
+
+   .. attribute:: category
+
+      Each :class:`Certificate` instance has a category:
+
+        >>> print mycertificate.category
+        None
+
+      .. XXX: This is not a proper description
+
+   .. attribute:: study_mode
+
+      Each :class:`Certificate` instance has a study mode:
+
+        >>> print mycertificate.study_mode
+        None
+
+      .. XXX: This is not a proper description
+
+   .. attribute:: start_level
+
+      Each :class:`Certificate` instance has a start level:
+
+        >>> print mycertificate.start_level
+        None
+
+      .. XXX: This is not a proper description
+
+   .. attribute:: end_level
+
+      Each :class:`Certificate` instance has a end level:
+
+        >>> print mycertificate.end_level
+        None
+
+      .. XXX: This is not a proper description
+   
+
+   .. attribute:: application_category
+
+      Each :class:`Certificate` instance has an application category:
+
+        >>> print mycertificate.application_category
+        None
+
+      .. XXX: This is not a proper description
+
+   
+   .. attribute:: m_prefix
+
+      Each :class:`Certificate` instance has an ``m_prefix``:
+
+        >>> print mycertificate.m_prefix
+        None
+
+      .. XXX: This is not a proper description
+
+   
+   .. attribute:: max_pass
+
+      Each :class:`Certificate` instance has a maximum number of passes:
+
+        >>> print mycertificate.max_pass
+        None
+
+      .. XXX: This is not a proper description
+
+
+   .. method:: check()
+
+      Mark a certificate instance's review state as ``checked``:
+
+        >>> mycertificate.review_state
+        'unchecked'
+
+        >>> mycertificate.check()
+        >>> mycertificate.review_state
+        'checked'
+
+      We cannot uncheck a certificate:
+
+        >>> mycertificate.review_state = 'init'
+        Traceback (most recent call last):
+	...
+	InvalidTransitionError: Transition 'init' requires 'None' 
+          as source state (is: 'checked')
+
+
+Utilities
+=========
+
+:class:`CertificateFactory`
+---------------------------
+
+.. class:: CertificateFactory()
+
+   .. attribute:: grok.name(u'waeup.Certificate')
+
+   .. attribute:: grok.implements(IFactory)
+
+   A named utility to deliver new instances of :class:`Certificate`
+   without the need to import the implementation before:
+
+     >>> from zope.component import createObject
+     >>> mycertificate = createObject(u'waeup.Certificate')
+     >>> mycertificate
+     <waeup.university.certificate.Certificate object at 0x...>
+
+Examples
+========
+
 
 We can create certificates:
@@ -30,55 +197,2 @@
     <waeup.university.certificate.Certificate object at 0x...>
 
-
-Certificate attributes
-======================
-
-Certificates have the attributes required by the `ICertificate` interface:
-
-    >>> from waeup.interfaces import ICertificate
-    >>> ICertificate.providedBy(mycertificate)
-    True
-
-    >>> from zope.interface.verify import verifyObject
-    >>> verifyObject(ICertificate, mycertificate)
-    True
-
-Each of the following attributes is mandatory.
-
-`title`
--------
-
-Each certificate has a title:
-
-    >>> mycertificate.title
-    u'Unnamed Certificate'
-
-`code`
-------
-
-Each certificate holds a code, which might be a shortcut or abbreviation
-of the real certificate name. By default the code is ``NA`` (=not assigned):
-
-    >>> mycertificate.code
-    u'NA'
-
-`review_state`
---------------
-
-The review state can have one of the ``checking`` states defined in
-the WAeUP workflow. These are at least the states ``checked`` and
-``unchecked``. After a certificate is created, the review state is
-``unchecked``:
-
-    >>> mycertificate.review_state
-    'unchecked'
-
-We can mark a certificate as checked:
-
-    >>> mycertificate.check()
-    >>> mycertificate.review_state
-    'checked'
-
-We cannot uncheck a certificate:
-
-    >>> mycertificate.review_state = 'init'
