More view documentation

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

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

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"