Add model docstrings.

Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>

mayan/apps/acls/models.py

@@ -18,9 +18,17 @@ logger = logging.getLogger(__name__)
 @python_2_unicode_compatible
 class AccessControlList(models.Model):
     """
-    Model that hold the permission, object, actor relationship
+    ACL means Access Control List it is a more fine-grained method of
+    granting access to objects. In the case of ACLs, they grant access using
+    3 elements: actor, permission, object. In this case the actor is the role,
+    the permission is the Mayan permission and the object can be anything:
+    a document, a folder, an index, etc. This means = "Grant X permissions
+    to role Y for object Z". This model holds the permission, object, actor
+    relationship for one access control list.
+    Fields:
+    * Role - Custom role that is being granted a permission. Roles are created
+    in the Setup menu.
     """
-
     content_type = models.ForeignKey(
         ContentType,
         related_name='object_content_type'

mayan/apps/converter/classes.py

@@ -216,6 +216,10 @@ class ConverterBase(object):
 
 
 class BaseTransformation(object):
+    """
+    Transformation can modify the appearance of the document's page preview.
+    Some transformation available are: Rotate, zoom, resize and crop.
+    """
     arguments = ()
     name = 'base_transformation'
     _registry = {}

mayan/apps/converter/models.py

@@ -21,8 +21,14 @@ class Transformation(models.Model):
     """
     Model that stores the transformation and transformation arguments
     for a given object
+    Fields:
+    * order - Order of a Transformation - In case there are multiple
+    transformations for an object, this field list the order at which
+    they will be execute.
+    * arguments - Arguments of a Transformation - An optional field to hold a
+    transformation argument. Example: if a page is rotated with the Rotation
+    transformation, this field will show by how many degrees it was rotated.
     """
-
     content_type = models.ForeignKey(ContentType)
     object_id = models.PositiveIntegerField()
     content_object = GenericForeignKey('content_type', 'object_id')

mayan/apps/django_gpg/models.py

@@ -23,6 +23,11 @@ logger = logging.getLogger(__name__)
 
 @python_2_unicode_compatible
 class Key(models.Model):
+    """
+    Fields:
+    * key_type - Will show private or public, the only two types of keys in
+    a public key infrastructure, the kind used in Mayan.
+    """
     key_data = models.TextField(
         help_text=_('ASCII armored version of the key.'),
         verbose_name=_('Key data')

mayan/apps/document_indexing/models.py

@@ -19,6 +19,10 @@ from .managers import (
 
 @python_2_unicode_compatible
 class Index(models.Model):
+    """
+    Parent model that defines an index and hold all the relationship for its
+    template and instance when resolved.
+    """
     label = models.CharField(
         max_length=128, unique=True, verbose_name=_('Label')
     )
@@ -65,7 +69,6 @@ class Index(models.Model):
         """
         Automatically create the root index template node
         """
-
         super(Index, self).save(*args, **kwargs)
         IndexTemplateNode.objects.get_or_create(parent=None, index=self)
 
@@ -102,6 +105,11 @@ class IndexInstance(Index):
 
 @python_2_unicode_compatible
 class IndexTemplateNode(MPTTModel):
+    """
+    The template to generate an index. Each entry represents a level in a
+    hierarchy of levels. Each level can contain further levels or a list of
+    documents but not both.
+    """
     parent = TreeForeignKey('self', blank=True, null=True)
     index = models.ForeignKey(
         Index, related_name='node_templates', verbose_name=_('Index')

mayan/apps/document_signatures/models.py

@@ -26,6 +26,16 @@ def upload_to(*args, **kwargs):
 
 @python_2_unicode_compatible
 class SignatureBaseModel(models.Model):
+    """
+    Fields:
+    * key_id - Key Identifier - This is what identifies uniquely a key. Not
+    two keys in the world have the same Key ID. The Key ID is also used to
+    locate a key in the key servers: http://pgp.mit.edu
+    * signature_id - Signature ID - Every time a key is used to sign something
+    it will generate a unique signature ID. No two signature IDs are the same,
+    even when using the same key.
+    """
+
     document_version = models.ForeignKey(
         DocumentVersion, editable=False, related_name='signatures',
         verbose_name=_('Document version')

mayan/apps/document_states/models.py

@@ -21,6 +21,11 @@ logger = logging.getLogger(__name__)
 
 @python_2_unicode_compatible
 class Workflow(models.Model):
+    """
+    Fields:
+    * label - Identifier. A name/label to call the workflow
+    """
+
     label = models.CharField(
         max_length=255, unique=True, verbose_name=_('Label')
     )
@@ -66,6 +71,16 @@ class Workflow(models.Model):
 
 @python_2_unicode_compatible
 class WorkflowState(models.Model):
+    """
+    Fields:
+    * completion - Completion Amount - A user defined numerical value to help
+    determine if the workflow of the document is nearing completion (100%).
+    The Completion Amount will be determined by the completion value of the
+    Actual State. Example: If the workflow has 3 states: registered, approved,
+    archived; the admin could give the follow completion values to the
+    states: 33%, 66%, 100%. If the Actual State of the document if approved,
+    the Completion Amount will show 66%.
+    """
     workflow = models.ForeignKey(
         Workflow, related_name='states', verbose_name=_('Workflow')
     )
@@ -155,6 +170,12 @@ class WorkflowInstance(models.Model):
             pass
 
     def get_current_state(self):
+        """
+        Actual State - The current state of the workflow. If there are
+        multiple states available, for example: registered, approved,
+        archived; this field will tell at the current state where the
+        document is right now.
+        """
         try:
             return self.get_last_transition().destination_state
         except AttributeError:
@@ -167,6 +188,10 @@ class WorkflowInstance(models.Model):
             return None
 
     def get_last_transition(self):
+        """
+        Last Transition - The last transition used by the last user to put
+        the document in the actual state.
+        """
         try:
             return self.get_last_log_entry().transition
         except AttributeError:
@@ -224,6 +249,13 @@ class WorkflowInstance(models.Model):
 
 @python_2_unicode_compatible
 class WorkflowInstanceLogEntry(models.Model):
+    """
+    Fields:
+    * user - The user who last transitioned the document from a state to the
+    Actual State.
+    * datetime - Date Time - The date and time when the last user transitioned
+    the document state to the Actual state.
+    """
     workflow_instance = models.ForeignKey(
         WorkflowInstance, related_name='log_entries',
         verbose_name=_('Workflow instance')

mayan/apps/documents/models.py

@@ -141,6 +141,10 @@ class DocumentType(models.Model):
 class Document(models.Model):
     """
     Defines a single document with it's fields and properties
+    Fields:
+    * uuid - UUID of a document, universally Unique ID. An unique identifier
+    generated for each document. No two documents can ever have the same UUID.
+    This ID is generated automatically.
     """
 
     uuid = models.UUIDField(default=uuid.uuid4, editable=False)
@@ -329,6 +333,18 @@ class DeletedDocument(Document):
 class DocumentVersion(models.Model):
     """
     Model that describes a document version and its properties
+    Fields:
+    * mimetype - File mimetype. MIME types are a standard way to describe the
+    format of a file, in this case the file format of the document.
+    Some examples: "text/plain" or "image/jpeg". Mayan uses this to determine
+    how to render a document's file. More information:
+    http://www.freeformatter.com/mime-types-list.html
+    * encoding - File Encoding. The filesystem encoding of the document's
+    file: binary 7-bit, binary 8-bit, text, base64, etc.
+    * checksum - A hash/checkdigit/fingerprint generated from the document's
+    binary data. Only identical documents will have the same checksum. If a
+    document is modified after upload it's checksum will not match, used for
+    detecting file tampering among other things.
     """
     _pre_open_hooks = {}
     _post_save_hooks = {}
@@ -444,7 +460,9 @@ class DocumentVersion(models.Model):
     def exists(self):
         """
         Returns a boolean value that indicates if the document's file
-        exists in storage
+        exists in storage. Returns True if the document's file is verified to
+        be in the document storage. This is a diagnostic flag to help users
+        detect if the storage has desynchronized (ie: Amazon's S3).
         """
         return self.file.storage.exists(self.file.name)
 
@@ -502,6 +520,9 @@ class DocumentVersion(models.Model):
 
     @property
     def page_count(self):
+        """
+        The number of pages that the document posses.
+        """
         return self.pages.count()
 
     def revert(self, _user=None):

mayan/apps/sources/models.py

@@ -154,6 +154,21 @@ class InteractiveSource(Source):
 
 
 class StagingFolderSource(InteractiveSource):
+    """
+    The Staging folder source is interactive but instead of displaying an
+    HTML form (like the Webform source) that allows users to freely choose a
+    file from their computers, shows a list of files from a filesystem folder.
+    When creating staging folders administrators choose a folder in the same
+    machine where Mayan is installed. This folder is then used as the
+    destination location of networked scanners or multifunctional copiers.
+    The scenario for staging folders is as follows: An user walks up to the
+    networked copier, scan several papers documents, returns to their
+    computer, open Mayan, select to upload a new document but choose the
+    previously defined staging folder source, now they see the list of
+    documents with a small preview and can proceed to process one by one and
+    convert the scanned files into Mayan EDMS documents. Staging folders are
+    useful when many users share a few networked scanners.
+    """
     is_interactive = True
     source_type = SOURCE_CHOICE_STAGING
 
@@ -234,6 +249,14 @@ class StagingFolderSource(InteractiveSource):
 
 
 class WebFormSource(InteractiveSource):
+    """
+    The webform source is an HTML form with a drag and drop window that opens
+    a file browser on the user's computer. This Source is interactive, meaning
+    users control live what documents they want to upload. This source is
+    useful when admins want to allow users to upload any kind of file as
+    documents from their own computers such as when each user has their own
+    scanner.
+    """
     is_interactive = True
     source_type = SOURCE_CHOICE_WEB_FORM
 
@@ -331,6 +354,15 @@ class IntervalBaseModel(OutOfProcessSource):
 
 
 class EmailBaseModel(IntervalBaseModel):
+    """
+    POP3 email and IMAP email sources are non-interactive sources that
+    periodically fetch emails from an email account using either the POP3 or
+    IMAP email protocol. These sources are useful when users need to scan
+    documents outside their office, they can photograph a paper document with
+    their phones and send the image to a designated email that is setup as a
+    Mayan POP3 or IMAP source. Mayan will periodically download the emails
+    and process them as Mayan documents.
+    """
     host = models.CharField(max_length=128, verbose_name=_('Host'))
     ssl = models.BooleanField(default=True, verbose_name=_('SSL'))
     port = models.PositiveIntegerField(blank=True, null=True, help_text=_(
@@ -572,6 +604,16 @@ class IMAPEmail(EmailBaseModel):
 
 
 class WatchFolderSource(IntervalBaseModel):
+    """
+    The watch folder is another non-interactive source that like the email
+    source, works by periodically checking and processing documents. This
+    source instead of using an email account, monitors a filesystem folder.
+    Administrators can define watch folders, examples /home/mayan/watch_bills
+    or /home/mayan/watch_invoices and users just need to copy the documents
+    they want to upload as a bill or invoice to the respective filesystem
+    folder. Mayan will periodically scan these filesystem locations and
+    upload the files as documents, deleting them if configured.
+    """
     source_type = SOURCE_CHOICE_WATCH
 
     folder_path = models.CharField(