From 63d15a6be3e99656c4db38d054e15215b1a094f8 Mon Sep 17 00:00:00 2001
From: Christopher Neugebauer <chrisjrn@gmail.com>
Date: Tue, 26 Apr 2016 10:52:56 +1000
Subject: [PATCH] More view documentation

---
 docs/views.rst                       | 29 +++++++++++++--
 registrasion/controllers/discount.py | 20 +++++++++++
 registrasion/models/commerce.py      | 53 ++++++++++++++++++++++++++--
 3 files changed, 98 insertions(+), 4 deletions(-)

diff --git a/docs/views.rst b/docs/views.rst
index ea30f748..96429a7d 100644
--- a/docs/views.rst
+++ b/docs/views.rst
@@ -1,11 +1,22 @@
-Public-facing views
-===================
+User-facing views
+=================
+
+
+View functions
+--------------
 
 Here's all of the views that Registrasion exposes to the public.
 
 .. automodule:: registrasion.views
     :members:
 
+Data types
+~~~~~~~~~~
+
+.. automodule:: registrasion.controllers.discount
+
+.. autoclass:: DiscountAndQuantity
+
 
 Template tags
 -------------
@@ -14,3 +25,17 @@ Registrasion makes template tags available:
 
 .. automodule:: registrasion.templatetags.registrasion_tags
     :members:
+
+
+Rendering invoices
+------------------
+
+You'll need to render the following Django models in order to view invoices.
+
+.. automodule:: registrasion.models.commerce
+
+.. autoclass:: Invoice
+
+.. autoclass:: LineItem
+
+.. autoclass:: PaymentBase
diff --git a/registrasion/controllers/discount.py b/registrasion/controllers/discount.py
index e73928d0..0544e980 100644
--- a/registrasion/controllers/discount.py
+++ b/registrasion/controllers/discount.py
@@ -8,6 +8,26 @@ from django.db.models import Sum
 
 
 class DiscountAndQuantity(object):
+    ''' Represents a discount that can be applied to a product or category
+    for a given user.
+
+    Attributes:
+
+        discount (conditions.DiscountBase): The discount object that the
+            clause arises from. A given DiscountBase can apply to multiple
+            clauses.
+
+        clause (conditions.DiscountForProduct|conditions.DiscountForCategory):
+            A clause describing which product or category this discount item
+            applies to. This casts to ``str()`` to produce a human-readable
+            version of the clause.
+
+        quantity (int): The number of times this discount item can be applied
+            for the given user.
+
+    '''
+
+
     def __init__(self, discount, clause, quantity):
         self.discount = discount
         self.clause = clause
diff --git a/registrasion/models/commerce.py b/registrasion/models/commerce.py
index 7e86acf2..a9fc7341 100644
--- a/registrasion/models/commerce.py
+++ b/registrasion/models/commerce.py
@@ -102,7 +102,39 @@ class DiscountItem(models.Model):
 @python_2_unicode_compatible
 class Invoice(models.Model):
     ''' An invoice. Invoices can be automatically generated when checking out
-    a Cart, in which case, it is attached to a given revision of a Cart. '''
+    a Cart, in which case, it is attached to a given revision of a Cart.
+
+    Attributes:
+
+        user (User): The owner of this invoice.
+
+        cart (commerce.Cart): The cart that was used to generate this invoice.
+
+        cart_revision (int): The value of ``cart.revision`` at the time of this
+            invoice's creation. If a change is made to the underlying cart,
+            this invoice is automatically void -- this change is detected
+            when ``cart.revision != cart_revision``.
+
+        status (int): One of ``STATUS_UNPAID``, ``STATUS_PAID``,
+            ``STATUS_REFUNDED``, OR ``STATUS_VOID``. Call
+            ``get_status_display`` for a human-readable representation.
+
+        recipient (str): A rendered representation of the invoice's recipient.
+
+        issue_time (datetime): When the invoice was issued.
+
+        due_time (datetime): When the invoice is due.
+
+        value (Decimal): The total value of the line items attached to the
+            invoice.
+
+        lineitem_set (Queryset[LineItem]): The set of line items that comprise
+            this invoice.
+
+        paymentbase_set(Queryset[PaymentBase]): The set of PaymentBase objects
+            that have been applied to this invoice.
+
+    '''
 
     class Meta:
         app_label = "registrasion"
@@ -165,7 +197,24 @@ class Invoice(models.Model):
 class LineItem(models.Model):
     ''' Line items for an invoice. These are denormalised from the ProductItems
     and DiscountItems that belong to a cart (for consistency), but also allow
-    for arbitrary line items when required. '''
+    for arbitrary line items when required.
+
+    Attributes:
+
+        invoice (commerce.Invoice): The invoice to which this LineItem is
+            attached.
+
+        description (str): A human-readable description of the line item.
+
+        quantity (int): The quantity of items represented by this line.
+
+        price (Decimal): The per-unit price for this line item.
+
+        product (Optional[inventory.Product]): The product that this LineItem
+            applies to. This allows you to do reports on sales and applied
+            discounts to individual products.
+
+    '''
 
     class Meta:
         app_label = "registrasion"