From 96b7053c5dd7e364139e4d05a5fc4e7703f36b3f Mon Sep 17 00:00:00 2001
From: wi11-holdsworth <83637728+wi11-holdsworth@users.noreply.github.com>
Date: Wed, 1 Oct 2025 14:32:16 +1000
Subject: [PATCH] docs: comment data structures

---
 Proj2.hs | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/Proj2.hs b/Proj2.hs
index b0677a3..489760e 100644
--- a/Proj2.hs
+++ b/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)