Further inline comments on bread model

bakerydemo/breads/models.py

@@ -18,7 +18,11 @@ class Country(models.Model):
     """
     A Django model to store set of countries of origin.
     It uses the `@register_snippet` decorator to allow it to be accessible
-    as via the Snippets UI (e.g. /admin/snippets/breads/country/)
+    via the Snippets UI (e.g. /admin/snippets/breads/country/) In the BreadPage
+    model you'll see we use a ForeignKey to create the relationship between
+    Country and BreadPage. This allows a single relationship (e.g only one
+    Country can be added) that is one-way (e.g. Country will have no way to
+    access related BreadPage objects).
     """
 
     title = models.CharField(max_length=100)
@@ -33,8 +37,11 @@ class Country(models.Model):
 @register_snippet
 class BreadIngredient(models.Model):
     """
-    Standard Django model used as a Snippet in the BreadPage model.
-    Demonstrates ManyToMany relationship.
+    Standard Django model that is displayed as a snippet within the admin due
+    to the `@register_snippet` decorator. We use a new piece of functionality
+    available to Wagtail called the ParentalManyToManyField on the BreadPage
+    model to display this. The Wagtail Docs give a slightly more detailed example
+    http://docs.wagtail.io/en/v1.9/getting_started/tutorial.html#categories
     """
     name = models.CharField(max_length=255)
 
@@ -52,7 +59,12 @@ class BreadIngredient(models.Model):
 @register_snippet
 class BreadType(models.Model):
     """
-    Standard Django model used as a Snippet in the BreadPage model.
+    A Django model to define the bread type
+    It uses the `@register_snippet` decorator to allow it to be accessible
+    via the Snippets UI. In the BreadPage model you'll see we use a ForeignKey
+    to create the relationship between BreadType and BreadPage. This allows a
+    single relationship (e.g only one BreadType can be added) that is one-way
+    (e.g. BreadType will have no way to access related BreadPage objects)
     """
 
     title = models.CharField(max_length=255)
@@ -79,6 +91,12 @@ class BreadPage(BasePageFieldsMixin, Page):
         null=True,
         blank=True,
     )
+
+    # We include related_name='+' to avoid name collisions on relationships. 
+    # e.g. there are two FooPage models in two different apps, 
+    # and they both have a FK to bread_type, they'll both try to create a 
+    # relationship called `foopage_objects` that will throw a valueError on
+    # collision.
     bread_type = models.ForeignKey(
         'breads.BreadType',
         null=True,
@@ -113,20 +131,31 @@ class BreadPage(BasePageFieldsMixin, Page):
 
 class BreadsIndexPage(BasePageFieldsMixin, Page):
     """
-    Index page for breads. We don't have any fields within our model but we need
-    to alter the page model's context to return the child page objects - the
-    BreadPage - so that it works as an index page.
+    Index page for breads.
+
+    This is more complex than other index pages on the bakery demo site as we've
+    included pagination. We've separated the different aspects of the index page
+    to be discrete functions to make it easier to follow
     """
 
+    # Can only have BreadPage children
     subpage_types = ['BreadPage']
 
+    # Returns a queryset of BreadPage objects that are live, that are direct
+    # descendants of this index page with most recent first
     def get_breads(self):
         return BreadPage.objects.live().descendant_of(
             self).order_by('-first_published_at')
 
+    # Allows child objects (e.g. BreadPage objects) to be accessible via the
+    # template. We use this on the HomePage to display child items of featured
+    # content
     def children(self):
         return self.get_children().specific().live()
 
+    # Pagination for the index page. We use the `django.core.paginator` as any
+    # standard Django app would, but the difference here being we have it as a
+    # method on the model rather than within a view function
     def paginate(self, request, *args):
         page = request.GET.get('page')
         paginator = Paginator(self.get_breads(), 12)
@@ -138,9 +167,12 @@ class BreadsIndexPage(BasePageFieldsMixin, Page):
             pages = paginator.page(paginator.num_pages)
         return pages
 
+    # Returns the above to the get_context method that is used to populate the
+    # template
     def get_context(self, request):
         context = super(BreadsIndexPage, self).get_context(request)
 
+        # BreadPage objects (get_breads) are passed through pagination
         breads = self.paginate(request, self.get_breads())
 
         context['breads'] = breads