Commented methods and variables

2 files changed, 57 insertions, 6 deletions

diff --git a/dev/pacmath.activity/question.py b/dev/pacmath.activity/question.py
index 860c464..d8205f7 100644
--- a/dev/pacmath.activity/question.py
+++ b/dev/pacmath.activity/question.py
@@ -13,6 +13,7 @@ class question:
     @var C: Properties of answer box [color, (left, top), center, ghost location]
     @var D: Properties of answer box [color, (left, top), center, ghost location]
     @var SIZE: Size of answer box
+    @var QUESTION_COLOR: the rgb color in which question text is written
     """
     # Properties of rectangles: [color, (left, top), center, ghost location]
     A = [(0, 180, 255), (625, 0), (735, 15), "./images/ghost.png"]
@@ -42,6 +43,10 @@ class question:
         self.pacman = pygame.image.load("./images/pacmanr.png").convert_alpha()
         
     def drawAnswers(self, screen):
+        """
+        Draws all answers in their color coded boxes
+        @param screen: The screen on which to draw
+        """
         self.drawAnswer(screen, self.questions[0][1], 1)
         self.drawAnswer(screen, self.questions[1][1], 2)
         self.drawAnswer(screen, self.questions[2][1], 3)
@@ -91,9 +96,8 @@ class question:
     # Draws the question
     def drawQuestion(self, screen):
         """
-        Draws the question
+        Draws the question to the screen
         @param screen: the screen in which we will draw
-        @param question: question to be drawn
         """
         # Font used
         font = pygame.font.Font(None, 72)
@@ -104,6 +108,10 @@ class question:
         screen.blit(q, (0, 640))
         pygame.display.flip()
     def drawPaused(self, screen):
+        """
+        Writes 'Paused' over where the question is usually printed
+        @param screen: the screen on which we will draw
+        """
         # Font used
         font = pygame.font.Font(None, 72)
         
@@ -112,15 +120,27 @@ class question:
         screen.blit(q, (0, 640))
         pygame.display.flip()
     def clearBottom(self, screen):
+        """
+        Draws a black box over the question-holding part of the screen
+        """
         blackBox = pygame.Surface((600,60))
         blackBox.fill((0,0,0))
         screen.blit(blackBox, (0,640))
 
     def getAnswerIndex(self):
+        """
+        Returns the integer index of the correct answer
+        @return the index
+        """
         return self.answerIndex
 
     # lives box is 35 px tall, ghosts are 25px square
     def updateLives(self, screen, count):
+        """
+        Redraws the lives display onto the screen
+        @param screen: the screen on which to draw
+        @param count: the number of lives we have
+        """
         self.clearLives(screen)
         offset = 0
         for i in range(count):
@@ -129,12 +149,21 @@ class question:
         pygame.display.update(pygame.Rect(900-offset, 640, offset, 30))
 
     def clearLives(self, screen):
+        """
+        Draws a black box over the lives display so we may redraw them
+        @param screen: the screen on which to draw
+        """
         blackBox = pygame.Surface((300,30))
         blackBox.fill((0,0,0))
         screen.blit(blackBox, (600,640))
         pygame.display.update(pygame.Rect(600, 640, 300, 30))
     
     def updateScore(self, screen, score):
+        """
+        Redraws the score onto the screen
+        @param screen: the screen on which we will draw
+        @param score: the score to be drawn
+        """
         self.clearScore(screen)
         
         text = pygame.font.Font(None, 36).render( "Score: " + str(score), 1, self.QUESTION_COLOR )
@@ -142,6 +171,10 @@ class question:
         pygame.display.update(pygame.Rect(900-text.get_width(), 670, text.get_width(), 30))
 
     def clearScore(self, screen):
+        """
+        Draws a black box over the score display so that we may redraw it
+        @param screen: the screen on which to draw
+        """
         blackBox = pygame.Surface((300,30))
         blackBox.fill((0,0,0))
         screen.blit(blackBox, (600,670))
diff --git a/dev/pacmath.activity/questionGenerator.py b/dev/pacmath.activity/questionGenerator.py
index a0b85be..b62453d 100644
--- a/dev/pacmath.activity/questionGenerator.py
+++ b/dev/pacmath.activity/questionGenerator.py
@@ -2,24 +2,34 @@
 """
 Creates random questions for PacMath
 @license: U{http://creativecommons.org/licenses/by-sa/3.0/us/}
-@var done: when game is done it will equal true
-@var MAZE_SIZE: size of maze
-@var MAZE_DRAW_FRAME: size of maze to be drawn
 """
 from random import randint
 import pygame
-import sys
 
 class questionGenerator:
+        """
+        A reusable object which is used to generate questions
+        @var operation: The operation that the math questions will incorporate
+        @var minOp: The minimum allowable value for an operand
+        @var maxOp: The maximum allowable value for an operand
+        """
 	def __init__(self, operation, minOp, maxOp):
         	"""
         	Constructor
+                @var operation: The operation that the math questions will incorporate
+                @var minOp: The minimum allowable value for an operand
+                @var maxOp: The maximum allowable value for an operand
        		"""
 		self.minOp = minOp
 		self.maxOp = maxOp
 		self.operation = operation
 	
 	def getQuestion(self):
+                """
+                Returns a single question based on the constraints the generator
+                was created with
+                @return A tuple contining two strings: ("question", "answer")
+                """
 		op1 = randint(self.minOp, self.maxOp)
 		op2 = randint(self.minOp, self.maxOp)
 		
@@ -39,6 +49,14 @@ class questionGenerator:
 		else:
 			return null
 	def getQuestionSet(self):
+                """
+                Returns a set of four questions for use in a round of pacmath, 
+                ensures that no questions have duplicate answers.
+                Fails and exits if four questions with distinct answers cannot
+                be generated from this constraint set (eg minOp = 2, maxOp = 3:
+                only 2 * 2, 2 * 3, 3 * 3)
+                @return A list with four questions in the form ("question", "answer")
+                """
 		questions = []
 		attempts = 0
 		while len(questions) < 4 and attempts < 100: