Commented the Candidates packages better

3 files changed, 27 insertions, 16 deletions

diff --git a/src/candidates-containers.adb b/src/candidates-containers.adb
index 9807f7a..a69a3a2 100644
--- a/src/candidates-containers.adb
+++ b/src/candidates-containers.adb
@@ -23,7 +23,6 @@ package body Candidates.Containers is
     is
         package My_CSV is new CSV;
         use Ada.Text_IO;
-        use type Ada.Containers.Count_Type;
         use type SU.Unbounded_String;
 
         Input_File        : File_Type;
@@ -38,9 +37,9 @@ package body Candidates.Containers is
         while not End_Of_File (Input_File) loop
             Current_Record := My_CSV.Parse_Line (Get_Line (Input_File));
 
-            --  all the field numbers here correspond to how
-            --  AEC Senate candidate data is arranged in csv format
-            if  Current_Record.Length = 25 and then
+            --  All the field numbers here correspond to how
+            --  AEC Senate candidate data is arranged in csv format.
+            if  Integer (Current_Record.Length) = 25 and then
                 Current_Record.Element (2) = "S" and then
                 Current_Record.Element (3) = State_Name'Image (State)
             then
@@ -61,9 +60,9 @@ package body Candidates.Containers is
 
 
 
-    --  these two types exist because I can't think of an easier
+    --  These types exist because I can't think of an easier
     --  way to sort a Candidate_Map into the appropriate order at
-    --  the moment
+    --  the moment.
 
     type Cand_Sort_Data is record
         Cand_ID    : CandidateID;
@@ -124,9 +123,11 @@ package body Candidates.Containers is
         while Current_Index <= Candidate_Data.Last_Index loop
             Current_Group := Candidate_Data.Element (Current_Index).Group;
 
-            --  the assumption is that the "UG" group is always last
-            --  a fairly safe assumption given alphabetical group order
-            --  but will break down should there be more than... 553 grouped candidates
+            --  The assumption is that the "UG" group is always last.
+            --  A fairly safe assumption given alphabetical group order
+            --  but will break down should there be more than 553 grouped candidates.
+            --  Fortunately, that will never happen because the CandidateIDs will
+            --  run out at 256 Candidates.
             exit when Current_Group = "UG";
 
             Working_Map := CandidateID_Maps.Empty_Map;
@@ -180,9 +181,9 @@ package body Candidates.Containers is
         for Cursor in Candidate_Data.Iterate loop
             Working_Candidate := Candidate_Maps.Element (Cursor);
             My_Candidate_Data.Append
-                  ((Cand_ID    => Candidate_Maps.Key (Cursor),
-                    Group      => Working_Candidate.Group,
-                    Group_Rank => Working_Candidate.Group_Rank));
+              ((Cand_ID    => Candidate_Maps.Key (Cursor),
+                Group      => Working_Candidate.Group,
+                Group_Rank => Working_Candidate.Group_Rank));
         end loop;
 
         Sorting.Sort (My_Candidate_Data);
diff --git a/src/candidates-containers.ads b/src/candidates-containers.ads
index a2ced26..f070b2e 100644
--- a/src/candidates-containers.ads
+++ b/src/candidates-containers.ads
@@ -42,7 +42,7 @@ package Candidates.Containers is
             Element_Type => CandidateID_Maps.Map);
 
 
-    --  possibly put some aspects here to ensure the types are as expected?
+    --  Possibly put some aspects here to ensure the types are as expected?
     subtype Above_Line_Ballot is CandidateID_Map_Maps.Map;
     subtype Below_Line_Ballot is CandidateID_Maps.Map;
 
@@ -53,13 +53,13 @@ package Candidates.Containers is
             Below_Ballot   :    out Below_Line_Ballot);
 
 
-    --  debugging function
+    --  Debugging function
     function To_String
            (Above_Ballot : in Above_Line_Ballot)
         return String;
 
 
-    --  debugging function
+    --  Debugging function
     function To_String
            (Below_Ballot : in Below_Line_Ballot)
         return String;
diff --git a/src/candidates.ads b/src/candidates.ads
index 548d03a..c0c310f 100644
--- a/src/candidates.ads
+++ b/src/candidates.ads
@@ -20,7 +20,9 @@ package Candidates is
     type Candidate is private;
 
 
-    --  this is restricted to 255 values for memory conservation reasons
+    --  This is restricted to 255 values for memory conservation reasons.
+    --  Should fit into a single byte each when Pragma Pack is applied
+    --  to an array of them.
     type CandidateID is new Positive range 1 .. 255;
 
 
@@ -31,17 +33,25 @@ package Candidates is
     No_Candidate : constant Extended_CandidateID := Extended_CandidateID'First;
 
 
+    --  The lack of getters/setters is intentional, to ensure that election
+    --  code cannot change Candidate data once initally read.
+
+
+    --  Returns the Candidate's fields in csv format for logging purposes.
     function To_String
            (Input_Candidate : in Candidate;
             Delimiter       : in Character := ',')
         return String;
 
 
+    --  Returns field labels corresponding to the field order
+    --  used in To_String. Used for logging purposes.
     function Candidate_Header
            (Delimiter : in Character := ',')
         return String;
 
 
+    --  Used for verbose console messages about a particular Candidate.
     function Name_And_Party
            (Input_Candidate : in Candidate)
         return String;