Add docstrings to all applicable classes and methods

1 files changed, 64 insertions, 21 deletions

diff --git a/PascalTriangle.activity/pascaltriangle.py b/PascalTriangle.activity/pascaltriangle.py
index d22aa26..63ccd3c 100755
--- a/PascalTriangle.activity/pascaltriangle.py
+++ b/PascalTriangle.activity/pascaltriangle.py
@@ -27,7 +27,17 @@ from gi.repository import Gtk, Gdk
 import cairo
 from gettext import gettext as _
 
+
 class PascalTriangleActivity(activity.Activity):
+    """Pascal's Triangle arithmetic activity.
+
+    This is a simple Sugar activity which presents Pascal's Triangle in the form
+    of a game, requiring the user to fill in blank cells in the triangle until
+    it is complete.
+
+    It supports multiple sizes of triangle, and also supports highlighting the
+    cells which contribute to the currently selected one.
+    """
     def __init__(self, handle):
         activity.Activity.__init__(self, handle, False)
 
@@ -108,10 +118,8 @@ class PascalTriangleActivity(activity.Activity):
         self.start_game()
 
 
-    """
-    Start a new game, clearing the previous game.
-    """
     def start_game(self):
+        """Start a new game, clearing the previous game and any alerts."""
         # Focus the drawing area so it can receive keyboard events.
         self._drawing_area.grab_focus()
 
@@ -132,21 +140,29 @@ class PascalTriangleActivity(activity.Activity):
 
 
     def _update_current_cell(self, index):
+        """Change position of the currently selected cell and clear any pending
+           text edits."""
         if index != self._current_cell:
             self._current_cell = index
             self._current_cell_text = ''
-            widget.queue_draw()
+            self._drawing_area.queue_draw()
 
 
-    """
-    Calculate the number of cells in the triangle. This is the Nth triangle
-    number, where N is the triangle_size. The formula for this is 1/2*N*(N+1).
-    """
     def _calculate_number_of_cells(self):
+        """Calculate the number of cells in the triangle.
+        
+        This is the Nth triangle number, where N is the triangle_size. The
+        formula for this is 1/2*N*(N+1).
+        """
         return self._triangle_size * (self._triangle_size + 1) / 2
 
 
     def _generate_blank_cell_list(self):
+        """Generate a non-empty list of random cell indices.
+        
+        All cells are guaranteed to exist in the current triangle and are
+        guaranteed to be unique.
+        """
         blank_cells = []
 
         # Generate a number of coordinates for blank cells, between 1 cell and
@@ -162,12 +178,12 @@ class PascalTriangleActivity(activity.Activity):
         return list(set(blank_cells))
 
 
-    """
-    Calculate the Pascal number for the (row, column) cell, where row and column
-    are both 0-based. This is equivalent to calculating the Binomial coefficient
-    of (row choose column).
-    """
     def _calculate_pascal_number(self, index):
+        """Calculate the Pascal number for the (row, column) cell.
+        
+        row and column are both 0-based. This is equivalent to calculating the
+        binomial coefficient of (row choose column).
+        """
         row = index[0]
         column = index[1]
 
@@ -177,6 +193,7 @@ class PascalTriangleActivity(activity.Activity):
 
 
     def __drawing_area_button_press_cb(self, widget, event, data = None):
+        """Handle a mouse button press in the drawing area."""
         # Check whether the click fell within a cell; if so, change the cell
         # selection.
         if event.type != Gdk.EventType.BUTTON_PRESS:
@@ -212,12 +229,15 @@ class PascalTriangleActivity(activity.Activity):
 
 
     def _is_cursor_in_radius(self, radius, cell_position, cursor_position):
+        """Calculate whether cursor_position falls within radius of
+           cell_position."""
         actual_radius_sq = (cell_position[0] - cursor_position[0]) ** 2 + \
                            (cell_position[1] - cursor_position[1]) ** 2
         return (actual_radius_sq <= radius ** 2)
 
 
     def __drawing_area_key_press_cb(self, widget, event, data = None):
+        """Handle a keyboard button press in the drawing area."""
         if event.type != Gdk.EventType.KEY_PRESS:
             return False
 
@@ -266,6 +286,7 @@ class PascalTriangleActivity(activity.Activity):
 
 
     def __drawing_area_draw_cb(self, widget, ctx, data = None):
+        """Redraw the drawing area and all its contents."""
         # Widget allocation and sizes. The cell_height is calculated weirdly
         # because the cells interlock as they tesselate; so for 2 rows, the
         # bottom third of the top row overlaps with the top third of the bottom
@@ -300,9 +321,12 @@ class PascalTriangleActivity(activity.Activity):
 
     def _calculate_cell_position(self, base_width, cell_width,
                                  cell_height, index):
-        # Calculate the cell position. Add an offset every odd row so
-        # the triangle is balanced. Each row is only 2/3 of cell_height
-        # because the hexagons interlock as they tesselate.
+        """Calculate the cell position.
+        
+        Add an offset every odd row so the triangle is balanced. Each row is
+        only 2/3 of cell_height because the hexagons interlock as they
+        tesselate.
+        """
         cell_x = self._padding + \
                  base_width / 2.0 - (cell_width / 2.0 * index[0]) + \
                  cell_width * index[1]
@@ -312,22 +336,32 @@ class PascalTriangleActivity(activity.Activity):
 
 
     def _get_cell_background(self, index):
+        """Get the background colour to use for the given cell."""
         if index == self._current_cell:
+            # Currently selected cell.
             return cairo.SolidPattern(0.541, 0.886, 0.204) # green
         elif self._show_hints and self._current_cell != (-1, -1) and \
              (self._current_cell[1] == 0 or \
               self._current_cell[1] == self._current_cell[0]) and \
              (index[1] == 0 or index[1] == index[0]):
+            # Hint all edge cells if the currently selected cell is on an edge.
             return cairo.SolidPattern(0.447, 0.624, 0.812) # blue
         elif self._show_hints and index[0] == self._current_cell[0] - 1 and \
              (index[1] == self._current_cell[1] - 1 or \
               index[1] == self._current_cell[1]):
+            # Hint the two cells above the currently selected cell.
             return cairo.SolidPattern(0.988, 0.914, 0.310) # yellow
         else:
+            # Non-selected, normal cell background.
             return cairo.SolidPattern(1.0, 1.0, 1.0) # white
 
 
     def _draw_cell(self, ctx, index, cell_width, cell_height):
+        """Draw a single cell.
+        
+        This draws the indexth cell at the current position in the given Cairo
+        context. The cell width and height are as given.
+        """
         centre = ctx.get_current_point()
 
         # Draw the cell outline as a hexagon and fill it.
@@ -371,12 +405,13 @@ class PascalTriangleActivity(activity.Activity):
             ctx.show_text(cell_text)
 
 
-    """
-    Check whether the user-entered text for the current cell matches the
-    expected value. If so, also check to see if the user's filled out all blank
-    cells and hence has won.
-    """
     def _check_current_cell_text(self):
+        """Check the user-entered text for the current cell.
+
+        If it matches the expected value, also check to see if the user's filled
+        out all blank cells and hence has won.
+        """
+
         # Check whether the answer is correct. If so, change the cell to be
         # uneditable.
         expected_num = self._calculate_pascal_number(self._current_cell)
@@ -406,13 +441,16 @@ class PascalTriangleActivity(activity.Activity):
 
 
     def __alert_response_cb(self, alert, response_id):
+        """Callback from the 'game over' alert."""
         self.start_game()
 
 
     def get_show_hints(self):
+        """Get whether hints should be rendered."""
         return self._show_hints
 
     def set_show_hints(self, val):
+        """Set whether hints should be rendered."""
         self._show_hints = val
         self._drawing_area.queue_draw()
 
@@ -420,6 +458,7 @@ class PascalTriangleActivity(activity.Activity):
 
 
     def __slider_value_changed_cb(self, widget, data = None):
+        """Handle value changes on the triangle size slider."""
         new_triangle_size = int(widget.get_value())
 
         if new_triangle_size != self._triangle_size:
@@ -429,6 +468,7 @@ class PascalTriangleActivity(activity.Activity):
 
 
 class NewGameButton(ToolButton):
+    """New Game toolbar button."""
     def __init__(self, parent_activity, **kwargs):
         ToolButton.__init__(self, 'add', **kwargs)
         self.props.tooltip = _('New Game')
@@ -437,10 +477,12 @@ class NewGameButton(ToolButton):
                      parent_activity)
 
     def __new_game_button_clicked_cb(self, button, parent_activity):
+        """Callback for the button to start a new game."""
         parent_activity.start_game()
 
 
 class HintButton(ToggleToolButton):
+    """Show Hints toolbar toggle button."""
     def __init__(self, parent_activity, **kwargs):
         ToggleToolButton.__init__(self, 'show-hints', **kwargs)
         #self.props.tooltip = 'Show Hints'
@@ -460,4 +502,5 @@ class HintButton(ToggleToolButton):
         self.connect('clicked', self.__hint_button_clicked_cb, parent_activity)
 
     def __hint_button_clicked_cb(self, button, parent_activity):
+        """Callback for the button to toggle the hint state."""
         parent_activity.show_hints = self.get_active()