added some JavaDoc comments and documentation

voting-booth/src/main/java/meerkat/voting/controller/selector/SimpleListCategoriesSelector.java

@@ -69,7 +69,7 @@ public class SimpleListCategoriesSelector implements QuestionSelector {
         assertDataValid();
     }
 
-    /*
+    /**
      * asserts that the selection data does not contain a question index which is beyond the length of
      * the ballot race questions array. Otherwise, throws an IndexOutOfBoundsException
      */
@@ -130,9 +130,11 @@ public class SimpleListCategoriesSelector implements QuestionSelector {
         return isSelected;
     }
 
-    /*
+    /**
      * Verifies that the ballot answer is of length 1. (We do not yet handle multi-choice questions in the channel choice round).
      * Otherwise, throws an exception.
+     * @param ballotAnswer
+     * @param questionNumber the number of the question (needed only for error message strings)
      */
     private void assertAnswerLengthIsOne (BallotAnswer ballotAnswer, int questionNumber) {
         if (ballotAnswer.getAnswerCount() != 1) {
@@ -157,8 +159,10 @@ public class SimpleListCategoriesSelector implements QuestionSelector {
         return selectedQuestions;
     }
 
-    /*
+    /**
      * copies a List of Integers into an int[] array of same length
+     * @param l a list of Integers
+     * @return an array of ints
      */
     private int[] listToIntArray(List<Integer> l) {
         int[] res = new int[l.size()];

voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManager.java

@@ -7,6 +7,7 @@ import java.security.SignatureException;
 
 /**
  * An interface for the encryptor component of the voting booth
+ * It handles both the encryption and the digital signature
  */
 public interface VBCryptoManager {
     /**

voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManagerImpl.java

@@ -11,13 +11,13 @@ import java.security.SignatureException;
 import java.util.Random;
 
 /**
- * Created by hai on 07/06/16.
+ * A basic implementation of the VBCryptoManager interface
  */
 public class VBCryptoManagerImpl implements VBCryptoManager {
 
     protected final static Logger logger = LoggerFactory.getLogger(VBCryptoManagerImpl.class);
 
-    private final Random random;
+    private final Random random;  //TODO: Random object should be more cryptographycally secure
     private final Encryption encryption;
     private final DigitalSignature digitalSignature;
 

voting-booth/src/main/java/meerkat/voting/output/AsyncRunnableOutputDevice.java

@@ -12,7 +12,9 @@ import org.slf4j.LoggerFactory;
 import java.util.concurrent.LinkedBlockingQueue;
 
 /**
- * Created by hai on 27/06/16.
+ * This is a base class for simple OutputDevices which run asynchronously (as a separate thread).
+ * The methods of the BallotOutputDevice simply register a matching OutputCommand in the instance's queue
+ * The Runnable.run method simply takes the next registered command and calls the matching (abstract) method
  */
 public abstract class AsyncRunnableOutputDevice implements BallotOutputDevice, Runnable  {
 
@@ -52,16 +54,10 @@ public abstract class AsyncRunnableOutputDevice implements BallotOutputDevice, R
         queue.clear();
     }
 
-
+    /**
-    abstract void doCommitToBallot(CommitOutputCommand command);
+     * chooses the next method to run according to the type of the given OutputCommand
-
+     * @param command any valid OutputCommand
-    abstract void doAudit(AuditOutputCommand command);
+     */
-
-    abstract void doCastBallot(CastOutputCommand command);
-
-    abstract void doCancel(CancelOutputCommand command);
-
-
     private void handleSingleCommand(OutputCommand command) {
         if (command instanceof CommitOutputCommand) {
             doCommitToBallot((CommitOutputCommand)command);
@@ -111,4 +107,28 @@ public abstract class AsyncRunnableOutputDevice implements BallotOutputDevice, R
     }
 
 
+    /**
+     * This method should be filled by an extending class. It should have the details of how to commit to a ballot
+     * @param command
+     */
+    abstract void doCommitToBallot(CommitOutputCommand command);
+
+    /**
+     * This method should be filled by an extending class. It should have the details of how to audit the ballot
+     * @param command
+     */
+    abstract void doAudit(AuditOutputCommand command);
+
+    /**
+     * This method should be filled by an extending class. It should have the details of how to cast the ballot
+     * @param command
+     */
+    abstract void doCastBallot(CastOutputCommand command);
+
+    /**
+     * This method should be filled by an extending class. It should have the details of how to cancel the ballot output
+     * @param command
+     */
+    abstract void doCancel(CancelOutputCommand command);
+
 }

voting-booth/src/main/java/meerkat/voting/output/BallotOutputDevice.java

@@ -20,7 +20,7 @@ public interface BallotOutputDevice {
 
     /**
      * Voter chose 'audit'. Output the ballot secrets to prove correctness of the encryption.
-     * @param ballotSecrets - the secrtes of the encryption
+     * @param ballotSecrets - the secrets of the encryption
      * @param callback - a callback object which expects no return value
      */
     public void audit(BallotSecrets ballotSecrets, FutureCallback<Void> callback);
@@ -37,5 +37,8 @@ public interface BallotOutputDevice {
      */
     public void cancelBallot(FutureCallback<Void> callback);
 
+    /**
+     * A method for shutting down the Output Device
+     */
     public void callShutDown();
 }

voting-booth/src/main/java/meerkat/voting/output/NetworkVirtualPrinter.java

@@ -20,20 +20,17 @@ import java.io.IOException;
 import static meerkat.pollingstation.PollingStationConstants.POLLING_STATION_WEB_SCANNER_SCAN_PATH;
 
 /**
- * Created by hai on 27/06/16.
+ * A ballot output device for the network. It simply sends details over the wire
  */
 public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice {
 
-    private Logger logger;
+    private static final Logger logger = LoggerFactory.getLogger(NetworkVirtualPrinter.class);
     private SignedEncryptedBallot signedEncryptedBallot;
     private final WebTarget successfulPrintTarget;
 
     public NetworkVirtualPrinter(String address) {
         super();
-
-        logger = LoggerFactory.getLogger(NetworkVirtualPrinter.class);
         logger.info("A NetworkVirtualPrinter is constructed");
-
         Client client = ClientBuilder.newClient();
         client.register(ProtobufMessageBodyReader.class);
         client.register(ProtobufMessageBodyWriter.class);
@@ -41,6 +38,12 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice {
     }
 
 
+    /**
+     * The NetworkVirtualPrinter actually does nothing for committing.
+     * It simply keeps the ballot details for later.
+     * When the voter chooses to Cast the ballot, these details are sent over the wire.
+     * @param command a CommitOutputCommand with the signed encryption of the ballot
+     */
     public void doCommitToBallot(CommitOutputCommand command) {
         logger.debug("entered method doCommitToBallot");
         signedEncryptedBallot = command.getSignedEncryptedBallot();
@@ -48,6 +51,9 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice {
     }
 
 
+    /**
+     * The NetworkVirtualPrinter actually does nothing for auditing.
+     */
     public void doAudit(AuditOutputCommand command) {
         logger.debug("entered method doAudit");
         signedEncryptedBallot = null;
@@ -55,6 +61,10 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice {
     }
 
 
+    /**
+     * This is where the magic happens. The signed encrypted ballot is transmitted over the wire
+     * @param command
+     */
     public void doCastBallot(CastOutputCommand command) {
         logger.debug("entered method doCastBallot");
         ScannedData scannedData = ScannedData.newBuilder()
@@ -75,6 +85,9 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice {
     }
 
 
+    /**
+     * The NetworkVirtualPrinter actually does nothing for canceling.
+     */
     public void doCancel(CancelOutputCommand command) {
         logger.debug("entered method doCancel");
         signedEncryptedBallot = null;

voting-booth/src/main/java/meerkat/voting/output/SystemConsoleOutputDevice.java

@@ -13,17 +13,18 @@ import org.slf4j.LoggerFactory;
  */
 public class SystemConsoleOutputDevice extends AsyncRunnableOutputDevice {
 
-    private Logger logger;
+    private static final Logger logger = LoggerFactory.getLogger(SystemConsoleOutputDevice.class);;
 
     public SystemConsoleOutputDevice () {
         super();
-        logger = LoggerFactory.getLogger(SystemConsoleOutputDevice.class);
         logger.info("A SystemConsoleOutputDevice is constructed");
     }
 
-
+    /**
-
+     * Committing to the ballot.
-
+     * Simply prints to the output stream all the details in the CommitOutputCommand.
+     * @param command details to commit to, and the callback to call when finished
+     */
     public void doCommitToBallot(CommitOutputCommand command) {
         logger.debug("entered method doCommitToBallot");
         PlaintextBallot plaintextBallot = command.getPlaintext();
@@ -43,6 +44,11 @@ public class SystemConsoleOutputDevice extends AsyncRunnableOutputDevice {
     }
 
 
+    /**
+     * auditing the ballot.
+     * prints to the output stream the ballot secrets (the encryption randomness and its proof of random generation)
+     * @param command An auditing command with the callback to finally call
+     */
     public void doAudit(AuditOutputCommand command) {
         logger.debug("entered method doAudit");
         System.out.println("Auditing");
@@ -52,7 +58,10 @@ public class SystemConsoleOutputDevice extends AsyncRunnableOutputDevice {
         command.getCallback().onSuccess(null);
     }
 
-
+    /**
+     * Casting the ballot (actually does nothing new)
+     * @param command
+     */
     public void doCastBallot(CastOutputCommand command) {
         logger.debug("entered method doCastBallot");
         System.out.println("Ballot finalized for casting!");
@@ -60,6 +69,10 @@ public class SystemConsoleOutputDevice extends AsyncRunnableOutputDevice {
     }
 
 
+    /**
+     * Canceling the ballot (actually does nothing new)
+     * @param command
+     */
     public void doCancel(CancelOutputCommand command) {
         logger.debug("entered method doCancel");
         System.out.println("Ballot cancelled!");

voting-booth/src/main/java/meerkat/voting/output/outputcommands/AuditOutputCommand.java

@@ -4,7 +4,7 @@ import meerkat.protobuf.Voting.*;
 import meerkat.voting.controller.callbacks.ControllerCallback;
 
 /**
- * Created by hai on 15/06/16.
+ * This OutputCommand supplies the necessary details for outputting Audit information
  */
 public class AuditOutputCommand extends OutputCommand {
 

voting-booth/src/main/java/meerkat/voting/output/outputcommands/CancelOutputCommand.java

@@ -3,7 +3,7 @@ package meerkat.voting.output.outputcommands;
 import meerkat.voting.controller.callbacks.ControllerCallback;
 
 /**
- * Created by hai on 15/06/16.
+ * This OutputCommand signals the output-device that it should Cancel the rest of the ballot output
  */
 public class CancelOutputCommand extends OutputCommand {
 

voting-booth/src/main/java/meerkat/voting/output/outputcommands/CastOutputCommand.java

@@ -3,7 +3,7 @@ package meerkat.voting.output.outputcommands;
 import meerkat.voting.controller.callbacks.ControllerCallback;
 
 /**
- * Created by hai on 15/06/16.
+ * This OutputCommand signals the output-device that the voter wishes to Cast the ballot
  */
 public class CastOutputCommand extends OutputCommand {
 

voting-booth/src/main/java/meerkat/voting/output/outputcommands/CommitOutputCommand.java

@@ -4,7 +4,7 @@ import meerkat.protobuf.Voting.*;
 import meerkat.voting.controller.callbacks.ControllerCallback;
 
 /**
- * Created by hai on 15/06/16.
+ * This OutputCommand supplies the necessary details for outputting a commit to the ballot
  */
 public class CommitOutputCommand extends OutputCommand {
 

voting-booth/src/main/java/meerkat/voting/output/outputcommands/OutputCommand.java

@@ -2,7 +2,9 @@ package meerkat.voting.output.outputcommands;
 
 import meerkat.voting.controller.callbacks.ControllerCallback;
 
-//TODO: make this class generic
+/**
+ * Base class for the commands to put in the output-device queue
+ */
 public abstract class OutputCommand {
     protected final ControllerCallback callback;