Add docstrings to views, models and signals

cart/contexts.py

@@ -8,7 +8,13 @@
 
 
 def cart_contents(request):
-
+"""
+View to return all information needed to display the cart, by
+converting what has been saved to the session into key variables.
+Protection in place in case a product, size or nic has been
+deleted while still in the cart, removing from the list before
+saving back to the cart session variable.
+"""
     cart_items = []
     total = 0
     savings = 0
@@ -36,7 +42,7 @@ def cart_contents(request):
             messages.error(request, 'An item was removed from your cart as it is \
                 no longer available. Try to find a worthy replacement!')
             continue
-
+        # Repeat for Size
         try:
             size = Size.objects.get(pk=size_id)
         except Size.DoesNotExist:
@@ -45,7 +51,7 @@ def cart_contents(request):
                 size is no longer available. \
                 Try to find a worthy replacement!')
             continue
-
+        # Repeat for Nicotine
         try:
             nic = Nicotine.objects.get(pk=nic_id)
         except Nicotine.DoesNotExist:
@@ -75,15 +81,19 @@ def cart_contents(request):
     original_total = total
     request.session['cart'] = cart
 
+    # Get user profile
     if request.user.is_authenticated:
         profile = get_object_or_404(UserProfile, user_id=request.user)
 
     else:
         profile = None
 
+    # Check for available points
     if profile:
         points_available = profile.points
 
+    # Check if user has chosen to redeem points and that the discount
+    # will never take the total below zero
     if discount_applied:
         if total - Decimal(points_available / 100) <= 0:
             total = 0

cart/views.py

@@ -7,6 +7,8 @@
 def view_cart(request):
     """ A view to return the shopping cart contents """
 
+    # Check whether on the cart page so that cart contents won't be repeated when
+    # they can already be seen
     context = {
         'on_cart_page': True,
     }
@@ -40,7 +42,6 @@ def add_to_cart(request, item_id):
     return redirect(redirect_url)
 
 
-# Want to update whole cart on form submit
 def update_cart(request, item_id):
     """ Update quantity of the chosen product in shopping cart """
 
@@ -89,7 +90,10 @@ def toggle_discount(request):
 
 def replicate_cart(request, order_number):
     """
-    Create a new cart filled with items/quantities from previous order
+    Create a new cart filled with items/quantities from previous order, and save
+    it to the session variable.
+    As deleted items are removed from past orders, there will not be a situation
+    where deleted products are added.
     """
     order = Order.objects.get(order_number=order_number)
     original_cart = eval(order.original_cart)

checkout/models.py

@@ -14,6 +14,9 @@
 
 
 class Order(models.Model):
+    """
+    A model for orders made by any user
+    """
     class Meta:
         ordering = ['-id']
 
@@ -88,6 +91,10 @@ def __str__(self):
 
 
 class OrderLineItem(models.Model):
+    """
+    A model for each row of an order, storing product, size,
+    nicotine content, quantity and the total
+    """
     order = models.ForeignKey(
         Order, null=False, blank=False,
         on_delete=models.CASCADE, related_name='lineitems')

checkout/views.py

@@ -36,6 +36,13 @@ def cache_checkout_data(request):
 
 
 def checkout(request):
+    """
+    Takes the data from an order form and creates an order in the DB.
+    Also checks whether a registered user has made the order and if they
+    have applied a discount, stores that information and sets their 
+    points to zero.
+
+    """
     stripe_public_key = settings.STRIPE_PUBLIC_KEY
     stripe_secret_key = settings.STRIPE_SECRET_KEY
 

products/models.py

@@ -6,6 +6,9 @@
 
 
 class Size(models.Model):
+    """
+    A model for product bottle sizes, price and sale price.
+    """
     label = models.CharField(max_length=50, null=True, blank=True)
     price = models.DecimalField(
         max_digits=4, decimal_places=2, null=True, blank=True)
@@ -17,6 +20,9 @@ def __str__(self):
 
 
 class Nicotine(models.Model):
+    """
+    A model for nicotine types and strengths.
+    """
     TYPE_CHOICES = (
         ('freebase', 'FREEBASE'),
         ('salt', 'SALT'),
@@ -31,6 +37,10 @@ def __str__(self):
 
 
 class Brand(models.Model):
+    """
+    A model for brands, each of which has various Sizes and Nicotines available
+    to it.
+    """
     class Meta:
         ordering = ['name']
 
@@ -48,6 +58,9 @@ def get_friendly_name(self):
 
 
 class Category(models.Model):
+    """
+    A model for broad flavour categories of vape juice.
+    """
     class Meta:
         verbose_name_plural = "Categories"
         ordering = ['name']
@@ -64,6 +77,10 @@ def get_friendly_name(self):
 
 
 class Tag(models.Model):
+    """
+    A model for the individual flavours of a Product, which can belong to many different
+    products.
+    """
     class Meta:
         ordering = ['name']
 
@@ -75,6 +92,10 @@ def __str__(self):
 
 
 class Product(models.Model):
+    """
+    A model for products and canonical information. Also stores whether or not
+    a product is for sale, the price for which is taken from the Sizes model.
+    """
     class Meta:
         ordering = ['-pk']
     name = models.CharField(max_length=50)
@@ -91,6 +112,10 @@ class Meta:
     created_on = models.DateTimeField(auto_now_add=True)
 
     def calculate_rating(self):
+        """
+        Aggregate the ratings of all related reviews to determine
+        product's average rating
+        """
         self.average_rating = self.reviews.all().aggregate(Avg("rating"))[
             'rating__avg']
         self.save()
@@ -100,6 +125,9 @@ def __str__(self):
 
 
 class ProductReview(models.Model):
+    """
+    A model to store reviews of products, created by users.
+    """
     class Meta:
         ordering = ['-created_on']
 

products/signals.py

@@ -7,15 +7,16 @@
 @receiver(post_save, sender=ProductReview)
 def update_rating_on_save(sender, instance, created, **kwargs):
     """
-    Update rating on product review update/create
+    Update a product's average rating on when a review
+    is created or updated.
     """
     instance.product.calculate_rating()
 
 
 @receiver(post_delete, sender=ProductReview)
 def update_rating_on_delete(sender, instance, **kwargs):
     """
-    Update rating on product review delete
+    Update a product's average rating when a review is deleted.
     """
     if instance.product:
         instance.product.calculate_rating()

products/templates/products/products.html

@@ -28,9 +28,7 @@ <h2 class="text-center">Sale</h2>
         <p class="product-filter-text">Grab your favourite Moose Juice while it's on sale!</p>
     {% else %}
         <h2 class="text-center">Moose Juice</h2>
-        <p class="product-filter-text">Lorem, ipsum dolor sit amet consectetur adipisicing elit. Modi eius laboriosam cumque
-            suscipit aperiam, facere id eum inventore perspiciatis atque? Sed quidem maiores veniam eius hic aspernatur, non
-            similique tempore.</p>
+        <p class="product-filter-text">We've built our business around Quality, Flavour and Choice - and we don't care who knows it! Our amazing chemists have revolutionised the way we think about e-liquid. They understand which flavours work best when combined with freebase or salt nicotine, and they always find the perfect PG/VG ratio to bring them out. </p>
     {% endif %}
 </header>
 

products/views.py

@@ -118,6 +118,9 @@ def product_detail(request, product_id):
 
 @login_required
 def favourites(request):
+    """
+    A view to return a user's favourites
+    """
     profile = get_object_or_404(UserProfile, user=request.user)
     products = profile.favourites.all()
     template = 'products/favourites.html'
@@ -131,6 +134,10 @@ def favourites(request):
 
 @login_required
 def toggle_favourite(request, product_id):
+    """
+    Add or remove a product from a user's list of favourites. Responds to
+    an ajax request made when heart icon is clicked.
+    """
 
     profile = get_object_or_404(UserProfile, user=request.user)
     product = get_object_or_404(Product, pk=product_id)
@@ -333,7 +340,7 @@ def edit_review(request, review_id):
 @login_required
 def delete_review(request, review_id):
     """
-    Delete a user's product review
+    Delete a user's product review (only if superuser).
     """
 
     if not request.user.is_superuser:

profiles/forms.py

@@ -3,6 +3,9 @@
 
 
 class UserProfileForm(forms.ModelForm):
+    """
+    Receives information about a user's default details.
+    """
     class Meta:
         model = UserProfile
         exclude = ('user', 'favourites', 'points')

profiles/models.py

@@ -11,7 +11,7 @@
 class UserProfile(models.Model):
     """
     User profile model for maintaining default delivery info,
-    order history and favourites
+    order history and favourites.
     """
     user = models.OneToOneField(User, on_delete=models.CASCADE)
 

profiles/views.py

@@ -47,6 +47,9 @@ def profile(request):
 
 @login_required
 def order_history(request, order_number):
+    """
+    Displays information about a user's order history.
+    """
     order = get_object_or_404(Order, order_number=order_number)
 
     template = 'checkout/checkout_success.html'

rewards/models.py

@@ -4,6 +4,11 @@
 
 
 class Reward(models.Model):
+    """
+    Stores types of reward and their values when awarded to users
+    on account creation, verified purchase reviews and purchases
+    made.
+    """
     type = models.CharField(max_length=254, null=True, blank=True)
     value = models.IntegerField(null=True, blank=True)
 
@@ -12,7 +17,9 @@ def __str__(self):
 
 
 class RewardHistory(models.Model):
-
+    """
+    The history of all the rewards and points a user has received.
+    """
     class Meta:
         verbose_name_plural = 'Reward History'
         ordering = ['-pk']