From 3a11e7132f315e4884f3de9595b77b6fb1e63c8e Mon Sep 17 00:00:00 2001
From: wi11-holdsworth <83637728+wi11-holdsworth@users.noreply.github.com>
Date: Wed, 1 Oct 2025 14:21:55 +1000
Subject: [PATCH] docs: add longer explanation assuming user is not familiar
 with the project

---
 Proj2.hs | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/Proj2.hs b/Proj2.hs
index 9869e36..143b9fa 100644
--- a/Proj2.hs
+++ b/Proj2.hs
@@ -3,6 +3,40 @@
 --
 -- Implements toPitch, feedback, initialGuess and nextGuess to efficiently
 -- play the game of musician as both the composer and the performer.
+--
+--
+-- The game of musician is two players, a composer and a performer. The
+-- composer initially creates a three-pitch chord, where each pitch is a
+-- usual musical note (A-G excluding flats and sharps) and an octave 1-3. The
+-- performer must then guess the chord. At each turn, the performer they
+-- provides a guess to the composer who returns with some feedback. The
+-- feedback contains the number of correct pitches in the performer's guess, as
+-- well as the number of correct notes and octaves in the composer's guess.
+--
+-- Note that notes and guesses are not double counted, e.g. if the performer
+-- has been told pitch A1 in their guess is correct, they will not also be
+-- told note A and octave 1 are correct (unless there are multiple instances of
+-- A and/or 1).
+--
+-- As the composer, we must do the following:
+--  1. create a chord for the performer to guess
+--  2. provide feedback on the performer's guess
+--
+-- 1. is taken care of by the testing framework, so we only need to handle 2.
+-- in this file. For pitches, find the intersection between the target and the
+-- guess. This will give us the correct pitches (and the number of them). Then
+-- we can remove the correct pitches from the target and the guess and split
+-- up the target and guess into notes and octaves. We then permute the target
+-- and match the guess with each permutation. To match means to count the
+-- number of pairwise equivalences, e.g. if we match the guess [1,2,3] with a
+-- permutation of the target [1,3,2], our "match value" is 2. This operation
+-- can be performed on the notes lists and the octaves lists to get the number
+-- of correct notes and octaves. This feedback is provided to the performer.
+--
+-- As the performer, we must guess the target in as few steps as possible given
+-- the feedback from the composer at each turn.
+--
+-- TODO: finish explanation of initialGuess and nextGuess
 
 module Proj2
   ( Pitch,