Documented ConsoleInterface

1 files changed, 90 insertions, 0 deletions

diff --git a/src/Generic/ConsoleInterface/Toolbox.cpp b/src/Generic/ConsoleInterface/Toolbox.cpp
index 78ca240..c46fff4 100644
--- a/src/Generic/ConsoleInterface/Toolbox.cpp
+++ b/src/Generic/ConsoleInterface/Toolbox.cpp
@@ -1,49 +1,93 @@
 #include "Toolbox.hpp"
 
+/*!
+ * Prints an ANSI escape sequence to clear the console. 
+ */
 void clear() {
 	// Clears console on Linux
 	// Source: https://stackoverflow.com/a/52895729/12036073
 	std::cout << u8"\033[2J\033[1;1H"; 
 }
 
+/*!
+ * Sub boxes are like normal boxes, but indented with 4 spaces.
+ */
 void _printSubBoxSpacing() {
 	std::cout << "    ";
 }
 
 /* Title boxes */
 
+/*! \param title C-style string, there are no size checks so it could wrap
+ *
+ * Prints the title, surrounded by "===".
+ */
 void titleBox(const char* title) {
 	std::cout << std::endl << "=== " << title << " ===" << std::endl;
 }
 
+/*! \param title C-style string, there are no size checks so it could wrap
+ *
+ * Prints the title, surrounded by "---".
+ */
 void subTitleBox(const char* title) {
 	std::cout << std::endl << "--- " << title << " ---" << std::endl;
 }
 
 /* Status boxes */
 
+/*! \param message C-style string, there are no size checks so it could wrap
+ *
+ * Success boxes start with "<S>" and print the message.
+ *
+ * \remark Success/Warning/Error boxes start with "<C>" where C is an appropriate character.
+ */
 void successBox(const char* message) {
 	std::cout << "<S> " << message << std::endl;
 }
 
+/*!
+ * Like successBox but also prints the sub box spacing
+ * \sa successBox()
+ */
 void successSubBox(const char* message) {
 	_printSubBoxSpacing();
 	successBox(message);
 }
 
+/*! \param message C-style string, there are no size checks so it could wrap
+ *
+ * Warning boxes start with "<W>" and print the message.
+ *
+ * \remark Success/Warning/Error boxes start with "<C>" where C is an appropriate character.
+ */
 void warningBox(const char* message) {
 	std::cout << "<W> " << message << std::endl;
 }
 
+/*!
+ * Like warningBox but also prints the sub box spacing
+ * \sa warningBox()
+ */
 void warningSubBox(const char* message) {
 	_printSubBoxSpacing();
 	warningBox(message);
 }
 
+/*! \param message C-style string, there are no size checks so it could wrap
+ *
+ * Error boxes start with "<E>" and print the message.
+ *
+ * \remark Success/Warning/Error boxes start with "<C>" where C is an appropriate character.
+ */
 void errorBox(const char* message) {
 	std::cout << "<E> " << message << std::endl;
 }
 
+/*!
+ * Like errorBox but also prints the sub box spacing
+ * \sa errorBox()
+ */
 void errorSubBox(const char* message) {
 	_printSubBoxSpacing();
 	errorBox(message);
@@ -51,6 +95,13 @@ void errorSubBox(const char* message) {
 
 /* Input line boxes */
 
+/*! \param label C-style string, there are no size checks so it could wrap
+ *
+ * Prints "(+)" and then the given label.
+ * It doesn't create spacing after label, so it should exist in the label itself.
+ *
+ * \remark Semi-internal means the function is defined in the header out of necessity (for templated functions)
+ */
 void _printInputBoxLabel(const char* label) {
 	std::cout << "(+) " << label;
 }
@@ -61,17 +112,34 @@ void __inputLineBoxGetInput(char* output, unsigned maxWidth, bool ignore) {
 	std::cin.getline(output, maxWidth);
 }
 
+/*! \param label C-style string, there are no size check so it could wrap
+ *  \param output Pointer to a char array
+ *  \param maxWidth Maximum count of characters to read from user input. output MUST be able to hold that many characters!
+ *  \param ignore Whether or not to ignore the first new-line delimiter.
+ *         true by default, should be set to false only when an inputLineBox/SubBox has been issued directly prior or when it's the very first issued box command.
+ *
+ *  Prints "(+)" before the label.
+ */
 void inputLineBox(const char* label, char* output, unsigned maxWidth, bool ignore) {
 	_printInputBoxLabel(label);
 	__inputLineBoxGetInput(output, maxWidth, ignore);
 }
 
+/*!
+ * Like inputLineBox but also prints the sub box spacing
+ * \sa inputLineBox()
+ */
 void inputLineSubBox(const char* label, char* output, unsigned maxWidth, bool ignore) {
 	_printSubBoxSpacing();
 	_printInputBoxLabel(label);
 	__inputLineBoxGetInput(output, maxWidth, ignore);
 }
 
+/*! \param ignore Whether or not to ignore the first new-line delimiter.
+ *         true by default, should be set to false only when an inputLineBox/SubBox has been issued directly prior or when it's the very first issued box command.
+ *
+ * Prints a "Press enter to continue" message and waits for the user
+ */
 void pressEnterToContinue(bool ignore) {
 	char tmp;
 	inputLineBox("[Press enter to continue]", &tmp, 1, ignore);
@@ -81,10 +149,22 @@ void pressEnterToContinue(bool ignore) {
 
 int orderedListIndex = 1;
 
+/*!
+ * Prints the latests ordered list index, surrounded by square brackets, and increments the ordered list index.
+ *
+ * \remark There are no size checks, so list index could overflow.
+ *
+ * \remark Semi-internal means the function is defined in the header out of necessity (for templated functions)
+ */
+
 void _printOrderedListBeginning() {
 	std::cout << "[" << orderedListIndex++ << "] ";
 }
 
+/*! \param starter Sets the starting number by which ordered list will enumerate
+ *
+ * \remark Although starter can be a negative number, ordered list will always increment up the number.
+ */
 void resetOrderedList(int starter) {
 	orderedListIndex = starter;
 }
@@ -113,6 +193,16 @@ void __printTableLine(unsigned columns) {
 	std::cout << ":" << std::endl;
 }
 
+/*! \param startNumber The number by which column and row enumeration begins
+ *  \params columns How many columns the table should have
+ *  \params items C-style string, each cell is a single character from the string
+ *
+ * Prints a string as a grid/table of characters from top to bottom, left to right.
+ * The first character is on the top left, the last one is on the bottom right.
+ *
+ * Table is printed until a terminating zero is encountered.
+ * The rows are "calculated" from the columns count and the items length.
+ */
 void table(unsigned startNumber, unsigned columns, const char* items) {
 	__printTableColumnHeader(startNumber, columns);