docs: 📝 add notes to test suite

src/tests/mutations/drawDefinitions/drawTypeSpecific/tallyPolicy.test.ts

@@ -106,11 +106,13 @@ test('roundRobinTally policy can specify groupTotals for both setsPct and gamesP
     const { gamesPct = 0 } = result;
     gamesPctTotal += gamesPct;
   });
+  // when the default tallyPolicy is used then the gamesPct is gamesWon/(gamesWon + gamesLost) for each participant
+  // ... so the total is always greater than 1.1
   expect(gamesPctTotal).toBeGreaterThan(1.1);
 
   const topLevelGroupTotalsPolicy = {
-    groupTotalGamesPlayed: true,
-    groupTotalSetsPlayed: true,
+    groupTotalGamesPlayed: true, // This tallyPolicy says that the denominator for gamesPct should always be ALL GAMES PLAYED BY ALL PARTICIPANTS
+    groupTotalSetsPlayed: true, // This tallyPolicy says that the denominator for setsPct should always be ALL SETS PLAYED BY ALL PARTICIPANTS
   };
   participantResults = tallyParticipantResults({
     policyDefinitions: { [POLICY_TYPE_ROUND_ROBIN_TALLY]: topLevelGroupTotalsPolicy },
@@ -122,15 +124,20 @@ test('roundRobinTally policy can specify groupTotals for both setsPct and gamesP
     const { gamesPct = 0 } = result;
     gamesPctTotal += gamesPct;
   });
+  // when the topLevelGroupTotalsPolicy is in force the total of all participants should equal 1
+  // ... in some scenarios it is .99999999999
   expect(Math.round(gamesPctTotal)).toEqual(1);
   expect(gamesPctTotal).toBeLessThan(1.1);
 
   const discreteGroupTotalsPolicy = {
     tallyDirectives: [
+      // ... <other preceding directives> ...
+      // This tallyDirective says that WHEN this tallyDirective comes into force...
+      // ...the denominator for setsPct should be ALL SETS PLAYED BY ALL PARTICIPANTS
       { attribute: 'setsPct', idsFilter: false, groupTotals: true },
+      // This tallyDirective says that WHEN this tallyDirective comes into force...
+      // ...the denominator for gamesPct should be ALL GAMES PLAYED BY ALL PARTICIPANTS
       { attribute: 'gamesPct', idsFilter: false, groupTotals: true },
-      { attribute: 'setsPct', idsFilter: true, groupTotals: true },
-      { attribute: 'gamesPct', idsFilter: true, groupTotals: true },
     ],
   };
   const result: any = tallyParticipantResults({
@@ -146,8 +153,11 @@ test('roundRobinTally policy can specify groupTotals for both setsPct and gamesP
     const { gamesPct = 0 } = result;
     gamesPctTotal += gamesPct;
   });
+  // when the discreteGroupTotalsPolicy is used the value in the participantResults does not reflect
+  // the computed value that is used in the tiebreaking.
   expect(gamesPctTotal).toBeGreaterThan(1.1);
 
+  // the value used in breaking ties can be seen in the report that is generated
   expect(result?.report?.[1].attribute).toEqual('setsPct');
   expect(result?.report?.[1].groupTotals).toEqual(true);
   expect(result?.report?.[2].attribute).toEqual('gamesPct');