--- a/PersonasBackend/personas/models.py	Fri Feb 15 05:31:46 2008 -0600
+++ b/PersonasBackend/personas/models.py	Fri Feb 15 11:17:53 2008 -0600
@@ -1,7 +1,26 @@
+"""
+models.py
+
+This module contains the models for the Personas application.
+
+Note that changes to Personas are automatically revision-controlled.
+Among other things, this allows for:
+
+  (A) A humane user interface that supports undo operations.
+
+  (B) A workflow that allows for Personas to be changed by a submitter
+      and reviewed while the original, unchanged Persona remains
+      published and accessible by clients.
+"""
+
 import datetime
 from django.db import models
 
 class User(models.Model):
+    """
+    Represents a user who can log into the Personas backend.
+    """
+
     name = models.CharField(
         "Name of the user",
         maxlength=100,
@@ -12,6 +31,11 @@
         return self.name
 
 class Category(models.Model):
+    """
+    Represents a Personas category; every Persona can be assigned one,
+    and only one, category.
+    """
+
     class Meta:
         verbose_name_plural = "categories"
 
@@ -25,6 +49,10 @@
         return self.name
 
 class Persona(models.Model):
+    """
+    Encapsulates the most recent revision of a Persona.
+    """
+
     MAX_NAME_LENGTH = 50
 
     name = models.CharField(
@@ -98,6 +126,8 @@
 
     date_updated = models.DateTimeField(
         "Update date for this revision",
+        # This ensures that this field is updated with the current
+        # timestamp whenever the record is changed.
         auto_now=True,
         null=False,
         )
@@ -125,11 +155,15 @@
                  ("deleted", "Deleted")),
         blank=False,
         default="published",
+        # TODO: Add help text for this, and figure out what all
+        # possible statuses are.
         )
 
     def __str__(self):
         return self.name
 
+    # These are the properties of this record that are "versioned",
+    # i.e. tracked by built-in revision control when changed.
     VERSIONED_PROPERTIES = (
         "name",
         "category",
@@ -208,6 +242,20 @@
         super(Persona, self).save()
 
 class Revision(models.Model):
+    """
+    Represents an old revision of a Persona.
+
+    This record only stores a "reverse delta" relative to the revision
+    that follows it; for instance, if a user changes a Persona at
+    revision 0 by modifying its description, then the Revision record
+    for revision 0 will contain only the description for the Persona
+    at that revision, since all other properties can be obtained by
+    looking at revision 1.  In this way, the complete "picture" of
+    revision 0 can be reconstructed by starting at the record for
+    revision 0 and traveling to newer revisions until every field of
+    the Persona has been populated.
+    """
+
     class Meta:
         unique_together = (("revision_of", "revision"),)
         ordering = ["revision"]