Added Javadoc comments to the classes

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

@@ -1,7 +1,23 @@
 //CipherStreamJava/src/main/java/com/mattrixwv/cipherstream/polysubstitution/Trifid.java
 //Mattrixwv
 // Created: 03-03-22
-//Modified: 04-19-24
+//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;
 
 
@@ -17,46 +33,92 @@ import com.mattrixwv.cipherstream.exceptions.InvalidInputException;
 import com.mattrixwv.cipherstream.exceptions.InvalidKeywordException;
 
 
+/**
+ * The {@code Trifid} class implements the Trifid cipher, a polyalphabetic substitution cipher
+ * that uses a 3x3x3 grid to encode and decode messages.
+ */
 public class Trifid{
 	private static final Logger logger = LoggerFactory.getLogger(Trifid.class);
 
-	//A class representing the location of a character in the grid
+	/** A class representing the location of a character in the grid */
 	protected class CharLocation{
+		/** The x location in the grid */
 		protected int x;
+		/** The y location in the grid */
 		protected int y;
+		/** The z location in the grid */
 		protected int z;
+		/**
+		 * Constructs a CharLocation with the specified x and y coordinates.
+		 *
+		 * @param x the x-coordinate of the character's location
+		 * @param y the y-coordinate of the character's location
+		 * @param z the z-coordinate of the character's location
+		 */
 		public CharLocation(int x, int y, int z){
 			this.x = x;
 			this.y = y;
 			this.z = z;
 		}
+		/**
+		 * Returns the x-coordinate of the character's location.
+		 *
+		 * @return the x-coordinate
+		 */
 		public int getX(){
 			return x;
 		}
+		/**
+		 * Returns the y-coordinate of the character's location.
+		 *
+		 * @return the y-coordinate
+		 */
 		public int getY(){
 			return y;
 		}
+		/**
+		 * Returns the z-coordinate of the character's location.
+		 *
+		 * @return the z-coordinate
+		 */
 		public int getZ(){
 			return z;
 		}
+		/**
+		 * Prints out the location in a human readable format
+		 */
 		public String toString(){
 			return "[" + (z + 1) + ", " + (x + 1) + ", " + (y + 1) + "]";
 		}
 	}
 
-	//Fields
-	protected String inputString;	//The message that needs to be encoded/decoded
-	protected String outputString;	//The encoded/decoded message
-	protected String keyword;		//The keyword used to create the grid
-	protected int groupSize;		//The size of the groups used to break up the input
-	protected char[][][] grid;		//The grid used to encode/decode the message
-	protected char fillIn;	//The character added to the alphabet to meet the 27 character requirement
-	//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 String keyword;
+	/** The size of the groups used to break up the input */
+	protected int groupSize;
+	/** The grid used to encode/decode the message */
+	protected char[][][] grid;
+	/** The character added to the alphabet to meet the 27 character requirement */
+	protected char fillIn;
+	//?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;
 
-	//Makes sure the fillIn is a valid character
+	/**
+	 * Sets the fill-in character used to complete the 27-character requirement for the grid.
+	 *
+	 * @param fillIn the fill-in character
+	 * @throws InvalidCharacterException if the fill-in character is not a printable non-letter character
+	 */
 	protected void setFillIn(char fillIn) throws InvalidCharacterException{
 		//Make sure the character is a printing character
 		if((fillIn < ' ') || (fillIn > '~')){
@@ -72,7 +134,13 @@ public class Trifid{
 		//Save the fillIn character
 		this.fillIn = fillIn;
 	}
-	//Strips invalid characters from the keyword and creates the grid
+	/**
+	 * Processes the keyword to generate the 3D grid. The keyword is sanitized to include
+	 * only capital letters and the fill-in character.
+	 *
+	 * @param keyword the keyword used to create the grid
+	 * @throws InvalidKeywordException if the keyword is invalid
+	 */
 	protected void setKeyword(String keyword) throws InvalidKeywordException{
 		//Ensure the keyword isn't null
 		if(keyword == null){
@@ -104,7 +172,9 @@ public class Trifid{
 		//Create the grid from the sanitized keyword
 		createGrid();
 	}
-	//Creates the grid from the keyword
+	/**
+	 * Creates the 3D grid from the processed keyword.
+	 */
 	protected void createGrid(){
 		logger.debug("Creating grid from keyword");
 
@@ -120,7 +190,12 @@ public class Trifid{
 
 		logger.debug("Completed grid\n{}", getGrid());
 	}
-	//Ensures groupSize constraints
+	/**
+	 * Sets the group size used for encoding and decoding the input string.
+	 *
+	 * @param groupSize the group size
+	 * @throws InvalidBaseException if the group size is less than or equal to zero
+	 */
 	protected void setGroupSize(int groupSize) throws InvalidBaseException{
 		if(groupSize <= 0){
 			throw new InvalidBaseException("Group size must be > 0");
@@ -130,7 +205,13 @@ public class Trifid{
 
 		this.groupSize = groupSize;
 	}
-	//Ensures inputString constraints
+	/**
+	 * Prepares the input string for encoding or decoding by applying preservation settings
+	 * and validating the input.
+	 *
+	 * @param inputString the input string to be processed
+	 * @throws InvalidInputException if the input string is invalid
+	 */
 	protected void setInputString(String inputString) throws InvalidInputException{
 		//Ensure the input string isn't null
 		if(inputString == null){
@@ -165,12 +246,22 @@ public class Trifid{
 			throw new InvalidInputException("Input must contain at least 1 letter");
 		}
 	}
-	//Returns the inputString with only letters
+	/**
+	 * Returns the input string with only valid letters and fill-in characters.
+	 *
+	 * @return the cleaned input string
+	 */
 	protected String getCleanInputString(){
 		logger.debug("Cleaning input string for encoding");
 		return inputString.toUpperCase().replaceAll("[^A-Z" + fillIn + "]", "");
 	}
-	//Returns the location of the given character in the grid
+	/**
+	 * Finds the location of a given character in the 3D grid.
+	 *
+	 * @param letter the character to find
+	 * @return the location of the character
+	 * @throws InvalidCharacterException if the character is not found in the grid
+	 */
 	protected CharLocation findChar(char letter) throws InvalidCharacterException{
 		logger.debug("Finding character {} in grid", letter);
 
@@ -189,7 +280,13 @@ public class Trifid{
 		//If it was not found something went wrong
 		throw new InvalidCharacterException("The character '" + letter + "' was not found in the grid");
 	}
-	//Return the character from the location provided
+	/**
+	 * Retrieves the character at the specified location in the 3D grid.
+	 *
+	 * @param location the location of the character
+	 * @return the character at the specified location
+	 * @throws InvalidCharacterException if the location is out of bounds
+	 */
 	protected char getChar(CharLocation location) throws InvalidCharacterException{
 		if(location.getX() > 2){
 			throw new InvalidCharacterException("x cannot be larget than 2");
@@ -205,7 +302,11 @@ public class Trifid{
 
 		return grid[location.getZ()][location.getX()][location.getY()];
 	}
-	//Adds all non-letter characters back to the output string
+	/**
+	 * Formats the output string according to the preservation settings.
+	 *
+	 * @param outputString the output string to format
+	 */
 	protected void formatOutput(String outputString){
 		logger.debug("Formatting output");
 
@@ -242,7 +343,11 @@ public class Trifid{
 		this.outputString = output.toString();
 		logger.debug("Formatted output '{}'", this.outputString);
 	}
-	//Encodes inputString using a polybius square and stores the result in outputString
+	/**
+	 * Encodes the input string using the Trifid cipher.
+	 *
+	 * @throws InvalidCharacterException if an invalid character is encountered
+	 */
 	protected void encode() throws InvalidCharacterException{
 		logger.debug("Encoding");
 
@@ -308,7 +413,11 @@ public class Trifid{
 		//Format the output
 		formatOutput(output.toString());
 	}
-	//Decodes inputString using a polybius square and stores the result in outputString
+	/**
+	 * Decodes the input string using the Trifid cipher.
+	 *
+	 * @throws InvalidCharacterException if an invalid character is encountered
+	 */
 	protected void decode() throws InvalidCharacterException{
 		logger.debug("Decoding");
 
@@ -380,7 +489,10 @@ public class Trifid{
 	}
 
 
-	//Constructor
+	//?Constructor
+	/**
+	 * Constructs a Trifid object with default settings.
+	 */
 	public Trifid() throws InvalidCharacterException{
 		preserveCapitals = false;
 		preserveWhitespace = false;
@@ -388,6 +500,13 @@ public class Trifid{
 		setFillIn('+');
 		reset();
 	}
+	/**
+	 * Constructs a Trifid object with default settings.
+	 *
+	 * @param preserveCapitals whether to preserve capital letters
+	 * @param preserveWhitespace whether to preserve whitespace
+	 * @param preserveSymbols whether to preserve symbols
+	 */
 	public Trifid(boolean preserveCapitals, boolean preserveWhitespace, boolean preserveSymbols) throws InvalidCharacterException{
 		this.preserveCapitals = preserveCapitals;
 		this.preserveWhitespace = preserveWhitespace;
@@ -395,6 +514,15 @@ public class Trifid{
 		setFillIn('+');
 		reset();
 	}
+	/**
+	 * Constructs a Trifid object with default settings.
+	 *
+	 * @param preserveCapitals whether to preserve capital letters
+	 * @param preserveWhitespace whether to preserve whitespace
+	 * @param preserveSymbols whether to preserve symbols
+	 * @param fillIn the character to use for fill-in characters
+	 * @throws InvalidCharacterException if the fill-in character is invalid
+	 */
 	public Trifid(boolean preserveCapitals, boolean preserveWhitespace, boolean preserveSymbols, char fillIn) throws InvalidCharacterException{
 		this.preserveCapitals = preserveCapitals;
 		this.preserveWhitespace = preserveWhitespace;
@@ -403,10 +531,32 @@ public class Trifid{
 		reset();
 	}
 
-	//Encodes inputString using keyword and groupSize and returns the result
+	/**
+	 * Encodes the specified input string using the provided keyword and group size.
+	 *
+	 * @param keyword the keyword used for encoding
+	 * @param inputString the input string to encode
+	 * @return the encoded string
+	 * @throws InvalidBaseException if the group size is invalid
+	 * @throws InvalidKeywordException if the keyword is invalid
+	 * @throws InvalidInputException if the input string is invalid
+	 * @throws InvalidCharacterException if an invalid character is encountered
+	 */
 	public String encode(String keyword, String inputString) throws InvalidBaseException, InvalidKeywordException, InvalidInputException, InvalidCharacterException{
 		return encode(keyword, inputString.length(), inputString);
 	}
+	/**
+	 * Encodes the specified input string using the provided keyword and group size.
+	 *
+	 * @param keyword the keyword used for encoding
+	 * @param groupSize the size of groups
+	 * @param inputString the input string to encode
+	 * @return the encoded string
+	 * @throws InvalidBaseException if the group size is invalid
+	 * @throws InvalidKeywordException if the keyword is invalid
+	 * @throws InvalidInputException if the input string is invalid
+	 * @throws InvalidCharacterException if an invalid character is encountered
+	 */
 	public String encode(String keyword, int groupSize, String inputString) throws InvalidBaseException, InvalidKeywordException, InvalidInputException, InvalidCharacterException{
 		//Set the parameters
 		reset();
@@ -418,10 +568,32 @@ public class Trifid{
 		encode();
 		return outputString;
 	}
-	//Decodes inputString using keyword and groupSize and returns the result
+	/**
+	 * Decodes the specified input string using the provided keyword and group size.
+	 *
+	 * @param keyword the keyword used for decoding
+	 * @param inputString the input string to decode
+	 * @return the decoded string
+	 * @throws InvalidBaseException if the group size is invalid
+	 * @throws InvalidKeywordException if the keyword is invalid
+	 * @throws InvalidInputException if the input string is invalid
+	 * @throws InvalidCharacterException if an invalid character is encountered
+	 */
 	public String decode(String keyword, String inputString) throws InvalidBaseException, InvalidKeywordException, InvalidInputException, InvalidCharacterException{
 		return decode(keyword, inputString.length(), inputString);
 	}
+	/**
+	 * Decodes the specified input string using the provided keyword and group size.
+	 *
+	 * @param keyword the keyword used for decoding
+	 * @param groupSize the size of groups
+	 * @param inputString the input string to decode
+	 * @return the decoded string
+	 * @throws InvalidBaseException if the group size is invalid
+	 * @throws InvalidKeywordException if the keyword is invalid
+	 * @throws InvalidInputException if the input string is invalid
+	 * @throws InvalidCharacterException if an invalid character is encountered
+	 */
 	public String decode(String keyword, int groupSize, String inputString) throws InvalidBaseException, InvalidKeywordException, InvalidInputException, InvalidCharacterException{
 		//Set the parameters
 		reset();
@@ -434,7 +606,9 @@ public class Trifid{
 		return outputString;
 	}
 
-	//Makes sure all variables are empty
+	/**
+	 * Resets all internal variables to their default values.
+	 */
 	public void reset(){
 		logger.debug("Resetting fields");
 
@@ -445,22 +619,52 @@ public class Trifid{
 		grid = new char[3][3][3];
 	}
 
-	//Getters
+	//?Getters
+	/**
+	 * Returns the current input string.
+	 *
+	 * @return the input string
+	 */
 	public String getInputString(){
 		return inputString;
 	}
+	/**
+	 * Returns the current output string.
+	 *
+	 * @return the output string
+	 */
 	public String getOutputString(){
 		return outputString;
 	}
+	/**
+	 * Returns the current keyword.
+	 *
+	 * @return the keyword
+	 */
 	public String getKeyword(){
 		return keyword;
 	}
+	/**
+	 * Returns the current group size.
+	 *
+	 * @return the group size
+	 */
 	public int getGroupSize(){
 		return groupSize;
 	}
+	/**
+	 * Returns the current fill-in character.
+	 *
+	 * @return the fill-in character
+	 */
 	public char getFillIn(){
 		return fillIn;
 	}
+	/**
+	 * Returns a string representation of the 3D grid.
+	 *
+	 * @return the grid as a string
+	 */
 	public String getGrid(){
 		logger.debug("Creating string from grid");