Added Javadoc comments to the classes

src/main/java/com/mattrixwv/cipherstream/polysubstitution/Hill.java

@@ -1,7 +1,23 @@
 //CipherStreamJava/src/main/java/com/mattrixwv/cipherstream/polysubstitution/Hill.java
 //Mattrixwv
 // Created: 01-31-22
-//Modified: 05-04-23
+//Modified: 08-11-24
+/*
+	Copyright (C) 2024  Mattrixwv
+
+	This program is free software: you can redistribute it and/or modify
+	it under the terms of the GNU Lesser General Public License as published by
+	the Free Software Foundation, either version 3 of the License, or
+	(at your option) any later version.
+
+	This program is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU Lesser General Public License for more details.
+
+	You should have received a copy of the GNU Lesser General Public License
+	along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
 package com.mattrixwv.cipherstream.polysubstitution;
 
 
@@ -18,20 +34,39 @@ import com.mattrixwv.matrix.exceptions.InvalidGeometryException;
 import com.mattrixwv.matrix.exceptions.InvalidScalarException;
 
 
+/**
+ * Implements the Hill cipher for encoding and decoding messages using matrix operations.
+ * <p>
+ * The Hill cipher is a polygraphic substitution cipher that uses linear algebra to encrypt and decrypt
+ * messages. It operates on blocks of text by representing them as vectors and applying matrix transformations.
+ * </p>
+ */
 public class Hill{
 	private static final Logger logger = LoggerFactory.getLogger(Hill.class);
-	//Fields
-	protected String inputString;	//The message that needs to be encoded/decoded
-	protected String outputString;	//The encoded/decoded message
-	protected char characterToAdd;	//The keyword used to create the grid
-	protected ModMatrix key;		//The matrix used perform the encoding/decoding
-	//Settings
-	protected boolean preserveCapitals;		//Persist capitals in the output string
-	protected boolean preserveWhitespace;	//Persist whitespace in the output string
-	protected boolean preserveSymbols;		//Persist symbols in the output string
+	//?Fields
+	/** The message that needs to be encoded/decoded */
+	protected String inputString;
+	/** The encoded/decoded message */
+	protected String outputString;
+	/** The keyword used to create the grid */
+	protected char characterToAdd;
+	/** The matrix used perform the encoding/decoding */
+	protected ModMatrix key;
+	//?Settings
+	/** Persist capitals in the output string */
+	protected boolean preserveCapitals;
+	/** Persist whitespace in the output string */
+	protected boolean preserveWhitespace;
+	/** Persist symbols in the output string */
+	protected boolean preserveSymbols;
 
 
-	//Validate and set the key
+	/**
+	 * Sets the key matrix for the Hill cipher after validating it.
+	 *
+	 * @param key the matrix to be used for encoding/decoding
+	 * @throws InvalidKeyException if the key is not a square matrix, or does not have an inverse modulo 26
+	 */
 	protected void setKey(ModMatrix key) throws InvalidKeyException{
 		logger.debug("Setting key");
 
@@ -60,7 +95,13 @@ public class Hill{
 		logger.debug("key\n{}", key);
 		this.key = new ModMatrix(key);
 	}
-	//Validate and set the input string
+	/**
+	 * Prepares and validates the input string for encoding by removing unwanted characters
+	 * and ensuring the length is appropriate.
+	 *
+	 * @param inputString the message to be encoded
+	 * @throws InvalidInputException if the input is null, blank, or its length is not a multiple of the matrix size
+	 */
 	protected void setInputStringEncode(String inputString) throws InvalidInputException{
 		logger.debug("Setting input string for encoding");
 
@@ -111,6 +152,13 @@ public class Hill{
 			throw new InvalidInputException("Input cannot be blank");
 		}
 	}
+	/**
+	 * Prepares and validates the input string for decoding by removing unwanted characters
+	 * and ensuring the length is appropriate.
+	 *
+	 * @param inputString the message to be decoded
+	 * @throws InvalidInputException if the input is null, blank, or its length is not a multiple of the matrix size
+	 */
 	protected void setInputStringDecode(String inputString) throws InvalidInputException{
 		logger.debug("Setting input string for decoding");
 
@@ -145,7 +193,11 @@ public class Hill{
 			throw new InvalidInputException("Length of input string must be a multiple of the number of rows in the key");
 		}
 	}
-	//Get a perfectly clean copy of input string
+	/**
+	 * Returns a clean version of the input string with only uppercase letters.
+	 *
+	 * @return the cleaned input string
+	 */
 	protected String getCleanInputString(){
 		logger.debug("Cleaning inputString");
 
@@ -154,7 +206,12 @@ public class Hill{
 
 		return cleanInputString;
 	}
-	//Validate and set character to add
+	/**
+	 * Sets the character used for padding the input string.
+	 *
+	 * @param characterToAdd the character to be used for padding
+	 * @throws InvalidCharacterException if the character is not a letter
+	 */
 	protected void setCharacterToAdd(char characterToAdd) throws InvalidCharacterException{
 		logger.debug("Setting character to add {}", characterToAdd);
 
@@ -173,7 +230,11 @@ public class Hill{
 		logger.debug("Cleaned character {}", characterToAdd);
 		this.characterToAdd = characterToAdd;
 	}
-	//Add capitalization, whitespace, and symbols to the output based on the input
+	/**
+	 * Restores capitalization, whitespace, and symbols to the output string based on the original input string.
+	 *
+	 * @return the polished output string
+	 */
 	protected String polishOutputString(){
 		logger.debug("Polishing output string");
 
@@ -203,7 +264,11 @@ public class Hill{
 		logger.debug("Polished string '{}'", cleanString);
 		return cleanString;
 	}
-	//Get vectors representing the input string
+	/**
+	 * Converts the cleaned input string into a list of column vectors based on the key matrix size.
+	 *
+	 * @return a list of vectors representing the input string
+	 */
 	protected ArrayList<ModMatrix> getInputVectors(){
 		logger.debug("Generating input vectors");
 
@@ -237,7 +302,12 @@ public class Hill{
 		//Return the array of vectors
 		return vectors;
 	}
-	//Get the string represented by the vectors that were passed in
+	/**
+	 * Converts a list of vectors back into a string representation.
+	 *
+	 * @param outputVectors the list of vectors to be converted
+	 * @return the resulting string
+	 */
 	protected String getOutputFromVectors(ArrayList<ModMatrix> outputVectors){
 		logger.debug("Turning vectors into a string");
 
@@ -257,7 +327,9 @@ public class Hill{
 		logger.debug("Converted string '{}'", convertedString);
 		return convertedString;
 	}
-	//Encode inputString and store the value in outputString
+	/**
+	 * Encodes the input string using the provided key matrix and stores the result in outputString.
+	 */
 	protected void encode(){
 		logger.debug("Encoding");
 
@@ -281,7 +353,9 @@ public class Hill{
 		//Add the extra characters back to the output and remove the added characters
 		outputString = polishOutputString();
 	}
-	//Decode inputString and store the value in outputString
+	/**
+	 * Decodes the input string using the provided key matrix and stores the result in outputString.
+	 */
 	protected void decode(){
 		logger.debug("Decoding");
 
@@ -308,7 +382,12 @@ public class Hill{
 		outputString = polishOutputString();
 	}
 
-	//Constructors
+	//?Constructors
+	/**
+	 * Default constructor initializing the cipher with default settings.
+	 *
+	 * @throws InvalidCharacterException if the default padding character is invalid
+	 */
 	public Hill() throws InvalidCharacterException{
 		preserveCapitals = false;
 		preserveWhitespace = false;
@@ -316,6 +395,14 @@ public class Hill{
 		setCharacterToAdd('x');
 		reset();
 	}
+	/**
+	 * Constructor initializing the cipher with specified settings.
+	 *
+	 * @param preserveCapitals if true, preserves capitals in the output string
+	 * @param preserveWhitespace if true, preserves whitespace in the output string
+	 * @param preserveSymbols if true, preserves symbols in the output string
+	 * @throws InvalidCharacterException if the default padding character is invalid
+	 */
 	public Hill(boolean preserveCapitals, boolean preserveWhitespace, boolean preserveSymbols) throws InvalidCharacterException{
 		this.preserveCapitals = preserveCapitals;
 		this.preserveWhitespace = preserveWhitespace;
@@ -323,6 +410,15 @@ public class Hill{
 		setCharacterToAdd('x');
 		reset();
 	}
+	/**
+	 * Constructor initializing the cipher with specified settings and padding character.
+	 *
+	 * @param preserveCapitals if true, preserves capitals in the output string
+	 * @param preserveWhitespace if true, preserves whitespace in the output string
+	 * @param preserveSymbols if true, preserves symbols in the output string
+	 * @param characterToAdd the character to use for padding
+	 * @throws InvalidCharacterException if the padding character is invalid
+	 */
 	public Hill(boolean preserveCapitals, boolean preserveWhitespace, boolean preserveSymbols, char characterToAdd) throws InvalidCharacterException{
 		this.preserveCapitals = preserveCapitals;
 		this.preserveWhitespace = preserveWhitespace;
@@ -331,20 +427,54 @@ public class Hill{
 		reset();
 	}
 
-	//Encode inputString using the provided key
+	/**
+	 * Encodes the input string using the provided key matrix and returns the encoded string.
+	 *
+	 * @param key the matrix to use for encoding
+	 * @param inputString the message to encode
+	 * @return the encoded message
+	 * @throws InvalidKeyException if the key is invalid
+	 * @throws InvalidInputException if the input is invalid
+	 */
 	public String encode(int[][] key, String inputString) throws InvalidKeyException, InvalidInputException{
 		return encode(new ModMatrix(key, 26), inputString);
 	}
+	/**
+	 * Encodes the input string using the provided key matrix and returns the encoded string.
+	 *
+	 * @param key the matrix to use for encoding
+	 * @param inputString the message to encode
+	 * @return the encoded message
+	 * @throws InvalidKeyException if the key is invalid
+	 * @throws InvalidInputException if the input is invalid
+	 */
 	public String encode(ModMatrix key, String inputString) throws InvalidKeyException, InvalidInputException{
 		setKey(key);
 		setInputStringEncode(inputString);
 		encode();
 		return outputString;
 	}
-	//Decode inputString using the provided key
+	/**
+	 * Decodes the input string using the provided key matrix and returns the decoded string.
+	 *
+	 * @param key the matrix to use for decoding
+	 * @param inputString the message to decode
+	 * @return the decoded message
+	 * @throws InvalidKeyException if the key is invalid
+	 * @throws InvalidInputException if the input is invalid
+	 */
 	public String decode(int[][] key, String inputString) throws InvalidKeyException, InvalidInputException{
 		return decode(new ModMatrix(key, 26), inputString);
 	}
+	/**
+	 * Decodes the input string using the provided key matrix and returns the decoded string.
+	 *
+	 * @param key the matrix to use for decoding
+	 * @param inputString the message to decode
+	 * @return the decoded message
+	 * @throws InvalidKeyException if the key is invalid
+	 * @throws InvalidInputException if the input is invalid
+	 */
 	public String decode(ModMatrix key, String inputString) throws InvalidKeyException, InvalidInputException{
 		setKey(key);
 		setInputStringDecode(inputString);
@@ -352,7 +482,9 @@ public class Hill{
 		return outputString;
 	}
 
-	//Makes sure all variables are empty
+	/**
+	 * Resets the Hill cipher by clearing all variables and setting the key to an empty matrix.
+	 */
 	public void reset(){
 		logger.debug("Resetting fields");
 
@@ -361,13 +493,28 @@ public class Hill{
 		key = new ModMatrix(26);
 	}
 
-	//Getters
+	//?Getters
+	/**
+	 * Returns the input string.
+	 *
+	 * @return the input string
+	 */
 	public String getInputString(){
 		return inputString;
 	}
+	/**
+	 * Returns the output string.
+	 *
+	 * @return the output string
+	 */
 	public String getOutputString(){
 		return outputString;
 	}
+	/**
+	 * Returns the key matrix used for encoding or decoding.
+	 *
+	 * @return the key matrix
+	 */
 	public ModMatrix getKey(){
 		return key;
 	}