Index: /main/waeup.sirp/trunk/src/waeup/sirp/accesscodes/accesscodes.py
===================================================================
--- /main/waeup.sirp/trunk/src/waeup/sirp/accesscodes/accesscodes.py	(revision 6498)
+++ /main/waeup.sirp/trunk/src/waeup/sirp/accesscodes/accesscodes.py	(revision 6499)
@@ -25,4 +25,39 @@
 class AccessCode(grok.Model):
     """An access code (aka PIN).
+
+    Implements
+    :class:`waeup.sirp.accesscodes.interfaces.IAccessCode`. :class:`AccessCode`
+    instances are normally part of an :class:`AccessCodeBatch` so
+    their representation (or code) is built with the containing batch
+    involved.
+
+    `batch_serial`
+       the serial number of the new :class:`AccessCode` inside its batch.
+
+    `random_num`
+       a 10-digit number representing the main part of the code.
+
+    :class:`AccessCode` instances normally have a representation (or
+    code) like
+
+      ``APP-XXX-YYYYYYYYYY``
+
+    where ``APP`` is the prefix of the containing batch, ``XXX`` is
+    the batch number and ``YYYYYYYYYY`` is the real code. The complete
+    PIN is portal-wide unique.
+
+    Access code instances are far more than simple strings. They have
+    a state, a history (so that all changes can be tracked) and a
+    cost (given as a float number).
+
+    The state of an access code is something like 'used', 'disabled',
+    etc. and determined by the workflow defined in
+    :mod:`waeup.sirp.accesscodes.workflow`. This also means that
+    instead of setting the status of an access code directly (you
+    can't do that easily, and yes, that's intentionally), you have to
+    trigger a transition (that might fail, if the transition is not
+    allowed in terms of logic or permissions). See
+    :mod:`waeup.sirp.accesscodes.workflow` for details.
+
     """
     grok.implements(IAccessCode)
@@ -35,4 +70,8 @@
     @property
     def representation(self):
+        """A string representation of the :class:`AccessCode`.
+
+        It has format ``APP-XXX-YYYYYYYYYY`` as described above.
+        """
         return '%s-%s-%s' % (
             self.batch_prefix, self.batch_num, self.random_num)
@@ -40,8 +79,12 @@
     @property
     def batch(self):
+        """The batch this :class:`AccessCode` is contained.
+        """
         return getattr(self, '__parent__', None)
 
     @property
     def batch_prefix(self):
+        """The prefix of the batch this :class:`AccessCode` belongs to.
+        """
         if self.batch is None:
             return ''
@@ -50,4 +93,7 @@
     @property
     def batch_num(self):
+        """The number of the batch this :class:`AccessCode` belongs to. A
+        read-only attribute.
+        """
         if self.batch is None:
             return ''
@@ -56,4 +102,6 @@
     @property
     def cost(self):
+        """A float representing the price or ``None``. A read-only attribute.
+        """
         if self.batch is None:
             return None
@@ -62,4 +110,6 @@
     @property
     def state(self):
+        """The workflow state. A read-only attribute.
+        """
         return IWorkflowState(self).getState()
 
