Improved commenting.

src/main/java/au/org/democracydevelopers/raireservice/persistence/entity/Contest.java

@@ -26,7 +26,8 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra
 /*
  * A contest class used for reading contest data out of the corla database.
  * This class omits the fields that are not relevant to input validation - we only care about
- * checking whether the request we received makes sense for IRV assertion generation or retrieval.
+ * checking whether any requests raire-service receives for assertion generation or retrieval make
+ * sense and are valid.
  */
 @Entity
 @Table(name = "contest")
@@ -47,40 +48,44 @@ public class Contest {
   @Column(name = "name", nullable = false, updatable = false)
   private String name;
 
-  public String getName() {
-    return name;
-  }
-
   /**
    * Description - should be either IRV or PLURALITY.
    */
   @ReadOnlyProperty
   @Column(name = "description", nullable = false, updatable = false)
   private String description;
 
-  public String getDescription() {
-    return description;
-  }
-
   /**
    * ID of county.
    */
   @ReadOnlyProperty
   @Column(name = "county_id", nullable = false, updatable = false)
   private long countyID;
 
-  public long getCountyID() {
-    return countyID;
-  }
-
   /**
    * Version. Used for optimistic locking.
    */
   @ReadOnlyProperty
   @Column(name = "version", nullable = false)
   private long version;
 
-  public long getVersion() {
-    return version;
+  /**
+   * Get the name of the contest.
+   * @return the name of the contest.
+   */
+  public String getName() {
+    return name;
+  }
+
+  /**
+   * Get the description, either "IRV" or "Plurality".
+   * @return the description.
+   */
+  public String getDescription() {
+    return description;
+  }
+
+  public long getCountyID() {
+    return countyID;
   }
 }

src/main/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepository.java

@@ -36,7 +36,7 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra
 public interface ContestRepository extends JpaRepository<Contest, Long> {
 
   /**
-   * Select contests by contest name
+   * Find and return all contests with a given name from the corla database.
    * Not used except in isAllIRV.
    * Spring syntactic sugar for the obvious SELECT query.
    * @param contestName the name of the contest.
@@ -45,15 +45,15 @@ public interface ContestRepository extends JpaRepository<Contest, Long> {
   List<Contest> findByName(String contestName);
 
   /**
-   * Find the first contest by name
+   * Find and return the first contest with a given name from the corla database.
    * @param contestName the name of the contest.
    * @return the first of that name,
    */
   Optional<Contest> findFirstByName(String contestName);
 
 
   /**
-   * Select contests by contest ID and county ID.
+   * Find and return contests by contest ID and county ID.
    * Contest ID is unique, so at most one result is possible.
    * @param contestID the ID of the contest
    * @param countyID the ID of the county
@@ -65,9 +65,9 @@ Optional<Contest> findByContestAndCountyID(@Param("contestID") long contestID,
 
   /**
    * Check whether all the contests of the given name have description 'IRV'.
+   * Note it does _not_ test for existence - use findFirstByName for that.
    * @param contestName the name of the contest
    * @return false if there are any non-IRV descriptions for a contest of that name.
-   * Note it does _not_ test for existence - use findFirstByName for that.
    */
   default boolean isAllIRV(String contestName) {
     List<Contest> contests = findByName(contestName);

src/main/java/au/org/democracydevelopers/raireservice/request/ContestRequest.java

@@ -27,7 +27,7 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra
 import org.springframework.data.annotation.ReadOnlyProperty;
 
 /**
- * Request (expected to be json) idenitfying a contest and listing its candidates.
+ * Request (expected to be json) identifying a contest by name and listing its candidates.
  * This is an abstract class containing only the core input & validation for contests -
  * just the contest name and list of candidates, plus basic methods to check that they are
  * present, non-null and IRV.
@@ -66,7 +66,7 @@ public ContestRequest(String contestName, List<String> candidates) {
   }
 
   /**
-   * Validates the contest request, checking that the contest exists and is an * IRV contest, and
+   * Validates the contest request, checking that the contest exists and is an IRV contest, and
    * that the contest request has candidates. Note it does _not_ check whether the candidates are
    * present in the CVRs.
    * @param contestRepository the respository for getting Contest objects from the database.

src/main/java/au/org/democracydevelopers/raireservice/request/GenerateAssertionsRequest.java

@@ -27,6 +27,15 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra
 /**
  * Request (expected to be json) identifying the contest for which assertions should be generated.
  * This extends ContestRequest and uses the contest name and candidate list, plus validations, from there.
+ * A GenerateAssertionsRequest identifies a contest by name along with the candidate list (which
+ * is necessary for producing the metadata for later visualization).
+ * TotalAuditableBallots states the total number of ballots in the universe, which may _not_ be the
+ * same as the number of CVRs that mention the contest.
+ * TimeLimitSeconds is a limit on the elapsed time that RAIRE has to do assertion generation.
+ * Validation consists only of checking that the request is reasonable, including calling
+ * ContestRequest.Validate to check that the contest exists and is all IRV, and that the candidate
+ * names are reasonable. GenerateAssertionsRequest.Validate then checks that the two numbers,
+ * totalAuditableBallots and timeLimitSeconds are positive.
  */
 public class GenerateAssertionsRequest extends ContestRequest {
 

src/main/java/au/org/democracydevelopers/raireservice/request/GetAssertionsRequest.java

@@ -29,6 +29,13 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra
  * Request (expected to be json) identifying the contest for which assertions should be retrieved
  * from the database (expected to be exported as json).
  * This extends ContestRequest and uses the contest name and candidate list, plus validations, from there.
+ * A GetAssertionsRequest identifies a contest by name along with the candidate list (which
+ * is necessary for producing the metadata for later visualization).
+ * riskLimit states the risk limit for the audit. This is not actually used in raire-service computations,
+ * but will be output later with the assertion export, so that it can be used in the assertion visualizer.
+ * Validation consists only of checking that the request is reasonable, including calling
+ * ContestRequest.Validate to check that the contest exists and is all IRV, and that the candidate
+ * names are reasonable. GetAssertionsRequest.Validate then checks that the risk limit is non-negative.
  */
 public class GetAssertionsRequest extends ContestRequest {
 
@@ -60,7 +67,7 @@ public GetAssertionsRequest(String contestName, List<String> candidates, BigDeci
    * Validates the request to retrieve assertions for the contest, checking that the contest exists
    * and is an IRV contest, that the risk limit has a sensible value, and that there are candidates.
    * Note it does _not_ check whether the candidates are present in the CVRs.
-   * @param contestRepository the respository for getting Contest objects from the database.
+   * @param contestRepository the repository for getting Contest objects from the database.
    * @throws RequestValidationException if the request is invalid.
    */
   public void Validate(ContestRepository contestRepository) throws RequestValidationException {

src/main/java/au/org/democracydevelopers/raireservice/request/RequestValidationException.java

@@ -20,6 +20,15 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra
 
 package au.org.democracydevelopers.raireservice.request;
 
+/**
+ * Exception indicating that a request failed validation. For a ContestRequest (including
+ * GenerateAssertionsRequest and GetAssertionRequest) this may be because:
+ * - the contest name is blank, or the candidate list is empty,
+ * - there is no contest of the requested name in the database,
+ * - the contest is not an IRV contest,
+ * - one of the numbers in the request (such as a time limit, risk limit, ballot count) is outside
+ *   the required range.
+ */
 public class RequestValidationException extends Exception {
 
   public RequestValidationException(String s) {

src/test/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepositoryTests.java

@@ -51,7 +51,7 @@ public class ContestRepositoryTests {
   private static final String ballinaMayoral = "Ballina Mayoral";
 
   /**
-   * Retrieval of a non-existent contest name retrieves nothing
+   * Retrieval of a non-existent contest name retrieves nothing.
    */
   @Test
   @Transactional
@@ -61,7 +61,7 @@ void retrieveZeroContests() {
   }
 
   /**
-   * Retrieval of all of a non-existent contest name retrieves nothing
+   * Retrieval of all of a non-existent contest name retrieves nothing.
    */
   @Test
   @Transactional
@@ -71,7 +71,7 @@ void retrieveAllZeroContests() {
   }
 
   /**
-   * Retrieving Ballina Mayoral by name works as expected
+   * Retrieving Ballina Mayoral by name works as expected.
    */
   @Test
   @Transactional
@@ -82,11 +82,10 @@ void retrieveBallinaMayoral() {
     assertEquals(ballinaMayoral, ballina.get().getName());
     assertEquals("IRV", ballina.get().getDescription());
     assertEquals(8L, ballina.get().getCountyID());
-    assertEquals(0L, ballina.get().getVersion());
   }
 
   /**
-   * Retrieving all matching Ballina Mayoral by name returns one item
+   * Retrieving all matching Ballina Mayoral by name returns one item.
    */
   @Test
   @Transactional
@@ -96,7 +95,7 @@ void retrieveAllBallinaMayoral() {
   }
 
   /**
-   * Retrieving all matching "Invalid Mixed Contest" by name returns both items
+   * Retrieving all matching "Invalid Mixed Contest" by name returns both items.
    */
   @Test
   @Transactional
@@ -116,7 +115,6 @@ void retrievePlurality() {
     assertEquals("Valid Plurality Contest",plurality.get().getName());
     assertEquals("Plurality", plurality.get().getDescription());
     assertEquals(10L, plurality.get().getCountyID());
-    assertEquals(0L, plurality.get().getVersion());
   }
 
   /**
@@ -162,7 +160,7 @@ void retrieveWronglyByCountyAndContestID2() {
   }
 
   /**
-   * A single IRV contest is correctly identified as all IRV
+   * A single IRV contest is correctly identified as all IRV.
    */
   @Test
   @Transactional
@@ -171,7 +169,7 @@ void singleIRVIsAllIRV() {
   }
 
   /**
-   * A non-existent contest is all IRV
+   * A non-existent contest is all IRV.
    */
   @Test
   @Transactional
@@ -180,7 +178,7 @@ void multiCountyIRVIsAllIRV() {
   }
 
   /**
-   * A single Plurality contest is not all IRV
+   * A single Plurality contest is not all IRV.
    */
   @Test
   @Transactional
@@ -190,7 +188,7 @@ void SinglePluralityIsNotAllIRV() {
 
 
   /**
-   * A (invalid) mixed contest is not all IRV
+   * A (invalid) mixed contest is not all IRV.
    */
   @Test
   @Transactional