From: Armaan Bhojwani <me@armaanb.net>
Date: Sun, 31 Jan 2021 17:18:05 +0000 (-0500)
Subject: Add comments to code
X-Git-Tag: v0.3.0~7
X-Git-Url: https://git.armaanb.net/?p=lightcards.git;a=commitdiff_plain;h=852be3a599b3686e20b2f3bfe10291380fcc5ff7

Add comments to code
---

diff --git a/lightcards/deck.py b/lightcards/deck.py
index 4a768b6..e3ef5c5 100644
--- a/lightcards/deck.py
+++ b/lightcards/deck.py
@@ -2,6 +2,7 @@
 # Armaan Bhojwani 2021
 
 class Card(list):
+    """Card extends the list class, and adds ability to star them."""
     starred = False
 
     def unStar(self):
@@ -27,6 +28,7 @@ class Card(list):
 
 
 class Status():
+    """The status class keeps track of where in the deck the user is"""
     index = 0
     side = 0
 
diff --git a/lightcards/display.py b/lightcards/display.py
index bdad1d1..71fec49 100755
--- a/lightcards/display.py
+++ b/lightcards/display.py
@@ -8,12 +8,19 @@ import textwrap
 
 
 def disp_bar(stdscr, stack, headers, obj):
+    """
+    Display the statusbar at the bottom of the screen with progress, star
+    status, and card side.
+    """
     (mlines, mcols) = stdscr.getmaxyx()
+
+    # Calculate percent done
     if len(stack) <= 1:
         percent = "100"
     else:
         percent = str(round(obj.getIdx() / (len(stack) - 1) * 100)).zfill(3)
 
+    # Put all the info together
     stdscr.insstr(mlines - 1, 0,
                   "[" +
                   stack[obj.getIdx()].printStar() +
@@ -32,6 +39,10 @@ def disp_bar(stdscr, stack, headers, obj):
 
 
 def disp_menu(stdscr, stack, headers, idx):
+    """
+    Display a menu once the end of the deck has been reached, offering
+    multiple options on how to continue.
+    """
     stdscr.addstr("Good job, you've completed a round!\n\n",
                   curses.color_pair(1))
     stdscr.addstr("Choose one of the following options:\n" +
@@ -53,6 +64,8 @@ def disp_menu(stdscr, stack, headers, idx):
                 x.unStar()
             get_key(stdscr, stack, headers, idx)
         elif key == "s":
+            # Check if there are any starred cards before proceeding, and if
+            # not, don't allow to proceed and show an error message
             cont = False
             for x in stack:
                 if x.getStar():
@@ -74,11 +87,17 @@ def disp_menu(stdscr, stack, headers, idx):
 
 
 def disp_card(stdscr, stack, headers, obj):
+    """
+    Display the contents of the card
+    Shows a header, a horizontal line, and the contents of the current side.
+    """
     stdscr.clear()
     (mlines, mcols) = stdscr.getmaxyx()
     if obj.getIdx() == len(stack):
         disp_menu(stdscr, stack, headers, obj)
     else:
+        # If on the back of the card, show the content of the front side in the
+        # header
         if obj.getSide() == 0:
             top = str(obj.getIdx() + 1) + " | " + headers[obj.getSide()]
         else:
@@ -107,6 +126,7 @@ def disp_card(stdscr, stack, headers, obj):
 
 
 def disp_help(stdscr, stack, headers, idx):
+    """Display help screen"""
     stdscr.clear()
     stdscr.addstr("LIGHTCARDS HELP SCREEN", curses.color_pair(1))
     stdscr.hline(1, 0, curses.ACS_HLINE, 23)
@@ -129,12 +149,19 @@ def disp_help(stdscr, stack, headers, idx):
 
 
 def init_disp(stdscr, stack, headers, idx):
-    curses.curs_set(0)
+    """Initialize curses options. Entrypoint into the display functions."""
+    curses.curs_set(0)  # Hide cursor
     curses.init_pair(1, curses.COLOR_CYAN, 0)
     curses.init_pair(2, curses.COLOR_RED, 0)
     get_key(stdscr, stack, headers, idx)
 
+
 def get_key(stdscr, stack, headers, idx):
+    """
+    Display a card and wait for the input.
+    Used as a general way of getting back into the card flow from a menu
+    """
+
     disp_card(stdscr, stack, headers, idx)
     while True:
         key = stdscr.getkey()
diff --git a/lightcards/lightcards.py b/lightcards/lightcards.py
index 2377c69..66d1231 100755
--- a/lightcards/lightcards.py
+++ b/lightcards/lightcards.py
@@ -33,6 +33,10 @@ def parse_args():
 
 
 def show(args, stack, headers):
+    """
+    Manipulate deck according to passed arguments, and send it to the display
+    functions
+    """
     idx = Status()
     if args.flip:
         for x in stack:
diff --git a/lightcards/parse.py b/lightcards/parse.py
index 6f3c25f..65cad62 100755
--- a/lightcards/parse.py
+++ b/lightcards/parse.py
@@ -10,11 +10,13 @@ from .deck import Card
 
 
 def md2html(file):
+    """Use the markdown module to convert input to HTML"""
     with open(file, "r", encoding="utf-8") as input_file:
         return markdown.markdown(input_file.read(), extensions=['tables'])
 
 
 def parse_html(html):
+    """Use BeautifulSoup to parse the HTML"""
     def clean_text(inp):
         return inp.get_text().rstrip()
 
@@ -30,6 +32,7 @@ def parse_html(html):
     for x in soup.find_all("tr"):
         outp.append(Card([clean_text(y) for y in x.find_all("td")]))
 
+    # Return a tuple of nested lists
     return ([clean_text(x) for x in soup.find_all("th")],
             clean_list(outp))