docs: comment data structures

Proj2.hs

@@ -54,8 +54,12 @@ import Debug.Trace
 
 -- ==== DATA STRUCTURES =======================================================
 
+-- TODO: INSERT COMMENT HERE
+--
 type GameState = [[Pitch]]
 
+-- represents a pitch, which is made of a note and a chord
+--
 data Pitch = Pitch
   { note :: Note,
     octave :: Octave
@@ -65,9 +69,13 @@ data Pitch = Pitch
 instance Show Pitch where
   show (Pitch note octave) = show note ++ show octave
 
+-- represents a standard musical note
+--
 data Note = A | B | C | D | E | F | G
   deriving (Bounded, Enum, Eq, Ord, Show)
 
+-- represents an octave of 1, 2 or 3
+--
 data Octave = One | Two | Three
   deriving (Bounded, Enum, Eq, Ord)
 
@@ -78,6 +86,12 @@ instance Show Octave where
 
 -- ==== REQUIRED FUNCTIONS ====================================================
 
+-- takes in a pitch-like string as input and outputs a pitch if conversion was
+-- successful, or nothing if it failed. a "pitch-like" string can be something
+-- like "A1" or "B2"
+--
+-- used in the testing framework as a utility function
+--
 toPitch :: String -> Maybe Pitch
 toPitch [note, octave] = Pitch <$> charToNote note <*> charToOctave octave
   where
@@ -103,6 +117,18 @@ toPitch [note, octave] = Pitch <$> charToNote note <*> charToOctave octave
         ]
 toPitch _ = Nothing
 
+-- takes a target chord (usually created by the composer) and a guess chord,
+-- and outputs an integer 3-tuple of feedback, where each element is the
+-- number of correct items in the guess:
+--
+--  (pitches, notes, octaves)
+--
+-- as per the explanation at the top of this file, notes and octaves are not
+-- double-counted
+--
+-- used in the testing framework as a utility function, and also by the
+-- performer to decide on the best guess to make each turn
+--
 feedback :: [Pitch] -> [Pitch] -> (Int, Int, Int)
 feedback target guess = (length correctPitches, correctNotes, correctOctaves)
   where
@@ -125,12 +151,15 @@ feedback target guess = (length correctPitches, correctNotes, correctOctaves)
     correctNotes = matches targetNotes guessNotes
     correctOctaves = matches targetOctaves guessOctaves
 
+-- TODO: comment me
+--
 initialGuess :: ([Pitch], GameState)
 initialGuess = (chord, chords)
   where
     chord : chords = allChords
 
--- implement me
+-- TODO: implement me
+--
 nextGuess :: ([Pitch], GameState) -> (Int, Int, Int) -> ([Pitch], GameState)
 nextGuess (prevGuess, chord : chords) _ = (chord, chords)