order fields in Version model

evolus/models.py

@@ -1,5 +1,5 @@
 """
-This module defines the structure and properties of documents.
+This module defines the structure and properties of documents and versions.
 """
 
 from django.db import models
@@ -143,24 +143,61 @@ class Document(models.Model):
 
 @reversion.register()
 class Version(models.Model):
+    """A version represents the writing steps of a document.
+
+    System fields::
+        major (+Int)
+        minor (+Int)
+        is_published (bool)
+        created_at (DateTime)
+
+    Properties:
+        audiences
+        keywords
+        sites
+        nodes
+        restricted
+
+    Actors:
+        Validators
+        Writers
+        Reviewers
+    """
+    # instance structure
     document = models.ForeignKey(Document, related_name='versions')
     file = models.FileField(upload_to='revisions/')
-    keywords = models.ManyToManyField(Keyword, blank=True, related_name='document_versions')
+
+    # system fields
     major = models.PositiveIntegerField()
     revision = models.PositiveIntegerField()
-    restricted = models.BooleanField(default=False)
     is_published = models.BooleanField(default=False)
-    revised_at = models.DateTimeField(null=True, blank=True)
-    authors = models.ManyToManyField(User, related_name='authors')
-    reviewers = models.ManyToManyField(User, related_name='reviewers')
-    validators = models.ManyToManyField(User, related_name='validators')
     created_at = models.DateTimeField(auto_now_add=True)
-    audiences = models.ManyToManyField(Audience, blank=True)
+
+    # properties
+    keywords = models.ManyToManyField(Keyword, blank=True, related_name='versions')
+    audiences = models.ManyToManyField(Audience, blank=True, related_name='versions')
+    restricted = models.BooleanField(default=False)
     sites = models.ManyToManyField(Site, blank=True)
     nodes = models.ManyToManyField(Node, blank=True)
 
+    # actors
+    authors = models.ManyToManyField(User, related_name='versions_as_author')
+    reviewers = models.ManyToManyField(User, related_name='versions_as_reviewer')
+    validators = models.ManyToManyField(User, related_name='versions_as_validator')
+
     @reversion.create_revision()
     def publish(self):
+        """Starts a new publication process, based on the people set as `validators`.
+
+        If the current version has not been published yet, this method checks that
+        there are people in the `validators` fields and assign a task to each one of them.
+
+        :exception
+            ActorException: when no validator has been set.
+
+        :returns
+            A new instance of type `process.Approval`.
+        """
         if not self.is_published:
             if self.validators.count() == 0:
                 raise ActorException('There are no validators for this version. \n'
@@ -172,6 +209,15 @@ class Version(models.Model):
 
     @reversion.create_revision()
     def update(self, *args, **kwargs):
+        """Update the current version by bumping its minor version by one.
+
+        This update can only occur when the current version has never been published.
+
+        :exception
+            ValueError when the current version has already been published.
+
+        :returns
+            super().save()"""
         if not self.is_published:
             self.revision = self.revision + 1
             return super().save(*args, **kwargs)