Fully documented generic classes

8 files changed, 269 insertions, 24 deletions

diff --git a/src/Generic/ConsoleInterface/Toolbox.cpp b/src/Generic/ConsoleInterface/Toolbox.cpp
index c46fff4..629c6ce 100644
--- a/src/Generic/ConsoleInterface/Toolbox.cpp
+++ b/src/Generic/ConsoleInterface/Toolbox.cpp
@@ -47,8 +47,8 @@ void successBox(const char* message) {
 }
 
 /*!
- * Like successBox but also prints the sub box spacing
- * \sa successBox()
+ * \copydetails successBox()
+ * \sa _printSubBoxSpacing()
  */
 void successSubBox(const char* message) {
 	_printSubBoxSpacing();
@@ -66,8 +66,8 @@ void warningBox(const char* message) {
 }
 
 /*!
- * Like warningBox but also prints the sub box spacing
- * \sa warningBox()
+ * \copydetails warningBox()
+ * \sa _printSubBoxSpacing()
  */
 void warningSubBox(const char* message) {
 	_printSubBoxSpacing();
@@ -85,8 +85,8 @@ void errorBox(const char* message) {
 }
 
 /*!
- * Like errorBox but also prints the sub box spacing
- * \sa errorBox()
+ * \copydetails errorBox()
+ * \sa _printSubBoxSpacing()
  */
 void errorSubBox(const char* message) {
 	_printSubBoxSpacing();
@@ -126,8 +126,8 @@ void inputLineBox(const char* label, char* output, unsigned maxWidth, bool ignor
 }
 
 /*!
- * Like inputLineBox but also prints the sub box spacing
- * \sa inputLineBox()
+ * \copydetails inputLineBox()
+ * \sa _printSubBoxSpacing()
  */
 void inputLineSubBox(const char* label, char* output, unsigned maxWidth, bool ignore) {
 	_printSubBoxSpacing();
diff --git a/src/Generic/ConsoleInterface/Toolbox.hpp b/src/Generic/ConsoleInterface/Toolbox.hpp
index ea1bba1..2686554 100644
--- a/src/Generic/ConsoleInterface/Toolbox.hpp
+++ b/src/Generic/ConsoleInterface/Toolbox.hpp
@@ -104,6 +104,7 @@ void inputBox(const char* label, T* output) {
 }
 
 //! Prints a label with sub box spacing and then reads user input and stores it
+//! \sa _printSubBoxSpacing()
 template <typename T>
 void inputSubBox(const char* label, T* output) {
 	_printSubBoxSpacing();
diff --git a/src/Generic/Date/Date.cpp b/src/Generic/Date/Date.cpp
index c5eeb9d..17228f9 100644
--- a/src/Generic/Date/Date.cpp
+++ b/src/Generic/Date/Date.cpp
@@ -20,7 +20,20 @@ unsigned short Date::daysInMonth() {
 
 Date::Date() : Date(01, 05, 2022) {}
 
-Date::Date(const char* str) {
+/*! \param str C-style string
+ *
+ * Values are initialized with zeroes. Then it parses the string:
+ *
+ * Skips spaces, saves day with atoi, skips two characters,
+ * skips spaces, saves month with atoi, skips two characters,
+ * skips spaces, saves year with atoi.
+ *
+ * Values are validated with setters.
+ * You should always have spaces between day, month and year and no non-numeric characters between them.
+ *
+ * \remark If there are non-numeric characters, as per atoi() spec, the appropriate property is zero.
+ */
+Date::Date(const char* str) : Date(0, 0, 0) {
 	while (*str == ' ' && *str != '\0') str++;
 	set_day(atoi(str));
 	str += 2;
@@ -31,6 +44,9 @@ Date::Date(const char* str) {
 	set_year(atoi(str));
 }
 
+/*!
+ * Initializes values with zeroes and then uses setters to save the function arguments.
+ */
 Date::Date(unsigned short day, unsigned short month, unsigned short year) {
 	this->day = this->month = this->year = 0;
 	set_day(day);
@@ -42,6 +58,10 @@ unsigned short Date::get_day() const {
 	return day;
 }
 
+/*! \return Whether newDay was saved or not
+ *
+ * If newDay is equal to 0, or is more than the appropriate days in the month, the day isn't set.
+ */
 bool Date::set_day(unsigned short newDay) {
 	if (newDay == 0 || newDay > daysInMonth())
 		return false;
@@ -52,6 +72,11 @@ bool Date::set_day(unsigned short newDay) {
 unsigned short Date::get_month() const {
 	return month;
 }
+
+/*! \return Whether newMonth was saved or not
+ *
+ * If newMonth is equal to 0 or is more than 12, the month isn't set.
+ */
 bool Date::set_month(unsigned short newMonth) {
 	if (newMonth == 0 || newMonth > 12)
 		return false;
@@ -62,6 +87,11 @@ bool Date::set_month(unsigned short newMonth) {
 unsigned short Date::get_year() const {
 	return year;
 }
+
+/*! \return Whether year was saved or not
+ *
+ * Year is always saved.
+ */
 bool Date::set_year(unsigned short newYear) {
 	year = newYear;
 	return true;
@@ -73,23 +103,43 @@ int digitToChar(unsigned digit) {
 	return ' ';
 }
 
+/*! \return String object in the format "day.month.year"
+ *
+ * \note Currently there isn't any way to change the formatting
+ */
 String Date::createString() const {
 	String out;
 	return ((((out += day) += ".") += month) += ".") += year;
 }
 
+/*! \param istr An input stream
+ *
+ * Directly reads bytes from stream (calls read() function).
+ * 
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ifstream
+ */
 void Date::read(std::istream& istr) {
 	istr.read((char*)&day, sizeof(day));
 	istr.read((char*)&month, sizeof(month));
 	istr.read((char*)&year, sizeof(year));
 }
 
+/*! \param ostr An output stream
+ *
+ * Directly writes bytes to stream (calls write() function).
+ * 
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ofstream
+ */
 void Date::write(std::ostream& ostr) {
 	ostr.write((char*)&day, sizeof(day));
 	ostr.write((char*)&month, sizeof(month));
 	ostr.write((char*)&year, sizeof(year));
 }
 
+/*! \returns -1 if this < other, 1 if this > other, 0 if this == other
+ */
 int Date::compare(const Date& other) const {
 	if (year < other.year || month < other.month || day < other.day)
 		return -1;
@@ -99,6 +149,11 @@ int Date::compare(const Date& other) const {
 
 /* Outside of class */
 
+/*!
+ * Uses the stream's >> operator to read and parse the day, month and year.
+ *
+ * \note Best used with std::cin or text std::ifstream
+ */
 std::istream& operator>>(std::istream& istr, Date& dt) {
 	unsigned short d, M, y;
 	istr >> d >> M >> y;
@@ -106,6 +161,11 @@ std::istream& operator>>(std::istream& istr, Date& dt) {
 	return istr;
 }
 
+/*!
+ * Uses the stream's << operator to write the date in the format "day.month.year"
+ *
+ * \note Best used with std::cout or text std::ofstream
+ */
 std::ostream& operator<<(std::ostream& ostr, const Date& dt) {
 	ostr << dt.get_day() << "." << dt.get_month() << "." << dt.get_year();
 	return ostr;
diff --git a/src/Generic/Date/Date.h b/src/Generic/Date/Date.h
index cb86e5f..89cc89c 100644
--- a/src/Generic/Date/Date.h
+++ b/src/Generic/Date/Date.h
@@ -1,10 +1,16 @@
 #ifndef HEADER_DATE
 #define HEADER_DATE
 
+/*! \file Date.h
+ *  \brief Stores the declaration of class Date
+ */
+
 #include <istream>
 #include <ostream>
 #include "../String/String.h"
 
+/*! \brief Stores a day, month and year
+ */
 class Date {
 	unsigned short day;
 	unsigned short month;
@@ -14,25 +20,40 @@ class Date {
 	unsigned short daysInMonth();
 
 public:
+	//! Sets date as 01 May 2022
 	Date();
+	//! Parses string
 	Date(const char* str);
+	//! Sets day, month and year
 	Date(unsigned short day, unsigned short month, unsigned short year);
 
+	//! Returns the day
 	unsigned short get_day() const;
+	//! Sets the day
 	bool set_day(unsigned short day);
+	//! Returns the month
 	unsigned short get_month() const;
+	//! Sets the month
 	bool set_month(unsigned short month);
+	//! Returns the year
 	unsigned short get_year() const;
+	//! Sets the year
 	bool set_year(unsigned short year);
 
+	//! Returns the date as a String object
 	String createString() const;
 
+	//! Reads date from stream
 	void read(std::istream& istr);
+	//! Writes date to stream
 	void write(std::ostream& ostr);
+	//! Compares two dates
 	int compare(const Date& other) const;
 };
 
+//! Reads date from stream with >> operator
 std::istream& operator>>(std::istream& istr, Date& dt);
+//! Writes date to stream with << operator
 std::ostream& operator<<(std::ostream& ostr, const Date& dt);
 
 #endif
diff --git a/src/Generic/List/List.hpp b/src/Generic/List/List.hpp
index c0ed51b..0b53033 100644
--- a/src/Generic/List/List.hpp
+++ b/src/Generic/List/List.hpp
@@ -1,9 +1,23 @@
 #ifndef HEADER_LIST
 #define HEADER_LIST
 
+/*! \file List.hpp
+ *  \brief Stores declaration and definition of templated class List
+ */
+
 #include <istream>
 #include <ostream>
 
+/*! \brief Templated class that stores an array of elements in dynamic memory
+ *
+ * \warning findIndex(), contain(), read(), write(), operator<<() and operator>>() require the type to have defined a couple of functions.
+ * \sa findIndex()
+ * \sa contain()
+ * \sa read()
+ * \sa write()
+ * \sa operator<<()
+ * \sa operator>>()
+ */
 template <typename T>
 class List {
 protected:
@@ -16,21 +30,33 @@ protected:
 	void copyFrom(const List& other);
 
 public:
+	//! Copies all elements in given array
 	List(const T* elements, unsigned elementsCount);
-	void add(T element);
-	void insertAt(T element, unsigned index);
+	//! Adds an element
+	void add(const T& element);
+	//! Inserts element at given index
+	void insertAt(const T& element, unsigned index);
+	//! Removes element at index
 	bool removeAt(unsigned index);
+	//! Finds the index of element
 	unsigned findIndex(const T& element) const;
 	bool contain(const T& element) const;
+	//! Returns reference to element at index
 	T& operator[](unsigned index);
+	//! Returns constant reference to element at index
 	const T& operator[](unsigned index) const;
 
+	//! Appends elements from other list
 	List<T>& operator+=(const List<T> other);
 
+	//! Reads from stream
 	std::istream& read(std::istream& istr);
+	//! Writes to stream
 	std::ostream& write(std::ostream& ostr) const;
 
+	//! Returns the length
 	unsigned get_length() const;
+	//! Returns the count
 	unsigned get_count() const;
 
 	List();
@@ -42,8 +68,10 @@ public:
 	List& operator=(List&& other);
 };
 
+//! Reads List from stream with >> operator
 template <typename T>
 std::istream& operator>>(std::istream& istr, List<T>& obj);
+//! Writes List to stream with << operator
 template <typename T>
 std::ostream& operator<<(std::ostream& ostr, const List<T>& obj);
 
@@ -84,15 +112,24 @@ List<T>::List(const T* elements, unsigned elementsCount) {
 		this->elements[i] = elements[i];
 }
 
+/*!
+ * Resizes internal array if there is no space for additional elements.
+ */
 template <typename T>
-void List<T>::add(T element) {
+void List<T>::add(const T& element) {
 	if (length == count) resize();
 
 	elements[count++] = element;
 }
 
+/*!
+ * If index is after the last element, the element is just added.
+ * Otherwise all elements after the index are shifted right and element is put in place.
+ *
+ * Resizes internal array if there is no space for additional elements.
+ */
 template <typename T>
-void List<T>::insertAt(T element, unsigned index) {
+void List<T>::insertAt(const T& element, unsigned index) {
 	if (index >= count) {
 		add(element);
 		return;
@@ -106,6 +143,11 @@ void List<T>::insertAt(T element, unsigned index) {
 	count++;
 }
 
+/*! \returns Wether element could be removed
+ *
+ * If index is after that of the last element, nothing is done and false is returned.
+ * Otherwise elements after index are shifted right and count is reduced.
+ */
 template <typename T>
 bool List<T>::removeAt(unsigned index) {
 	if (index >= count) return false;
@@ -116,6 +158,11 @@ bool List<T>::removeAt(unsigned index) {
 	return true;
 }
 
+/*! \returns Index of element. If element isn't found, returns the count of element.
+ *
+ * \warning The function depends on the type having a function "compare" defined, which takes two elements and returns a number <0 if elem1 < elem2, >0 if elem1 > elem2, 0 if elem1 == elem2
+ * \note Searching is done linearly
+ */
 template <typename T>
 unsigned List<T>::findIndex(const T& element) const {
 	unsigned ind = 0;
@@ -124,6 +171,11 @@ unsigned List<T>::findIndex(const T& element) const {
 	return ind;
 }
 
+/*! \returns Whether the element is contained in the current List
+ *
+ * \warning Function depends on findIndex(), which means the same "compare" function must be defined in the type
+ * \sa findIndex()
+ */
 template <typename T>
 bool List<T>::contain(const T& element) const {
 	return findIndex(element) < count;
@@ -146,6 +198,15 @@ List<T>& List<T>::operator+=(const List<T> other) {
 	return *this;
 }
 
+/*! \param istr An input stream
+ *
+ * Directly reads bytes from stream (calls read() function).
+ * Any stored values are deleted and replaced with those from the stream.
+ * 
+ * \warning The function depends on the type having a function "read" defined, which takes an std::istream& and writes it's data to it. Return type doesn't matter.
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ifstream
+ */
 template <typename T>
 std::istream& List<T>::read(std::istream& istr) {
 	istr.read((char*)&length, sizeof(length));
@@ -160,6 +221,14 @@ std::istream& List<T>::read(std::istream& istr) {
 	return istr;
 }
 
+/*! \param ostr An output stream
+ *
+ * Directly writes bytes to stream (calls write() function).
+ * 
+ * \warning The function depends on the type having a function "write" defined, which takes an std::ostream& and writes it's data to it. Return type doesn't matter.
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ofstream
+ */
 template <typename T>
 std::ostream& List<T>::write(std::ostream& ostr) const {
 	ostr.write((const char*)&length, sizeof(length));
@@ -171,11 +240,17 @@ std::ostream& List<T>::write(std::ostream& ostr) const {
 	return ostr;
 }
 
+/*!
+ * Length is the size of the underlying array (allocated memory).
+ */
 template <typename T>
 unsigned List<T>::get_length() const {
 	return length;
 }
 
+/*!
+ * Count is the amount of elements that are stored.
+ */
 template <typename T>
 unsigned List<T>::get_count() const {
 	return count;
@@ -227,8 +302,15 @@ List<T>& List<T>::operator=(List&& other) {
 	return *this;
 }
 
-/* Friend functions */
+/* Outside of class */
 
+/*!
+ * Uses the stream's >> operator to read and parse the elements.
+ * The first item in the stream should be the count.
+ *
+ * \warning The function depends on the type having the operator >> defined, which takes an std::istream& and writes it's data to it. Return type doesn't matter.
+ * \note Best used with std::cin or text std::ifstream
+ */
 template <typename T>
 std::istream& operator>>(std::istream& istr, List<T>& obj) {
 	List<T> newObj;
@@ -244,6 +326,12 @@ std::istream& operator>>(std::istream& istr, List<T>& obj) {
 	return istr;
 }
 
+/*!
+ * Uses the stream's << operator to write the count and then all objects.
+ *
+ * \warning The function depends on the type having the operator << defined, which takes an std::ostream& and writes it's data to it. Return type doesn't matter.
+ * \note Best used with std::cout or text std::ofstream
+ */
 template <typename T>
 std::ostream& operator<<(std::ostream& ostr, const List<T>& obj) {
 	ostr << obj.get_count() << std::endl;
diff --git a/src/Generic/List/OrderedList.hpp b/src/Generic/List/OrderedList.hpp
index 069bd4a..8d13a5d 100644
--- a/src/Generic/List/OrderedList.hpp
+++ b/src/Generic/List/OrderedList.hpp
@@ -1,28 +1,47 @@
 #ifndef HEADER_ORDEREDLIST
 #define HEADER_ORDEREDLIST
 
+/*! \file OrderedList.hpp
+ *  \brief Stores declaration and definition of templated class OrderedList
+ */
+
 #include "List.hpp"
 
-template <class T>
+/*! \brief Inherits List, but contains it's elements in a sorted manner
+ *
+ * \warning Outside those defined in List, insert() requires the type to have defined a "compare" of functions.
+ * \sa insert()
+ */
+template <typename T>
 class OrderedList : public List<T> {
 public:
 	OrderedList();
 	OrderedList(const T* elements, unsigned elementsCount);
 
+	/*! \brief \warning Function is deleted, use insert() instead
+	 * \sa insert()
+	 */
 	void add(T element) = delete;
+	/*! \brief \warning Function is deleted, use insert() instead
+	 * \sa insert()
+	 */
 	void insertAt(T element, unsigned index) = delete;
 
+	//! Inserts an element at a sorted position
 	void insert(T element);
-	// unsigned findIndex(const T& element) const; TODO: binary search
 };
 
-template <class T>
+template <typename T>
 OrderedList<T>::OrderedList() : OrderedList(nullptr, 0) {}
 
-template <class T>
+template <typename T>
 OrderedList<T>::OrderedList(const T* elements, unsigned elementsCount) : List<T>::List(elements, elementsCount) {}
 
-template <class T>
+/*!
+  * \warning The function depends on the type having a function "compare" defined, which takes two elements and returns a number <0 if elem1 < elem2, >0 if elem1 > elem2, 0 if elem1 == elem2
+  * \note Insertion is done linearly
+ */
+template <typename T>
 void OrderedList<T>::insert(T element) {
 	if (List<T>::length == List<T>::count) List<T>::resize();
 
diff --git a/src/Generic/String/String.cpp b/src/Generic/String/String.cpp
index eb157a2..49c0b19 100644
--- a/src/Generic/String/String.cpp
+++ b/src/Generic/String/String.cpp
@@ -15,12 +15,17 @@ void String::copyFrom(const String& other) {
 
 /* Public */
 
+/*!
+ * Allocated with length + 1 size, so there is a terminating zero at the end.
+ */
 String::String(unsigned length) {
 	this->length = length;
 	str = new char[length + 1];
 	str[length] = '\0';
 }
 
+/*! \params str C-style string
+ */
 String::String(const char* str) {
 	length = strlen(str);
 	this->str = new char[length + 1]; // capture terminating zero
@@ -35,6 +40,12 @@ unsigned String::get_length() const {
 	return length;
 }
 
+char& String::operator[](unsigned index) {
+	return str[index];
+}
+
+/*! \params str C-style string
+ */
 String& String::operator+=(const char* str) {
 	unsigned strLen = strlen(str);
 	char* newStr = new char[length + strLen + 1];
@@ -48,6 +59,9 @@ String& String::operator+=(const char* str) {
 	return *this;
 }
 
+/*!
+ * Converts the number to a C-style string and then uses += to append it.
+ */
 String& String::operator+=(unsigned number) {
 	unsigned tempLen = number / 10 + 1;
 	char* tmp = new char[tempLen + 1];
@@ -94,24 +108,45 @@ String& String::operator=(String&& other) {
 	return *this;
 }
 
+/*! \param istr An input stream
+ *
+ * Directly reads bytes from stream (calls read() function).
+ * First reads the string length, then the underlying C-style string (including terminating zero).
+ * 
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ifstream
+ */
 void String::read(std::istream& istr) {
 	istr.read((char*)&length, sizeof(length));
 	istr.read(str, sizeof(char) * (length + 1));
 }
 
+/*! \param ostr An output stream
+ *
+ * Directly writes bytes to stream (calls write() function).
+ * First writes the string length, then the underlying C-style string (including terminating zero).
+ * 
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ofstream
+ */
 void String::write(std::ostream& ostr) const {
 	ostr.write((char*)&length, sizeof(length));
 	ostr.write(str, sizeof(char) * (length + 1));
 }
 
+/*! \params other C-style string
+ *  \returns strcmp between underlying C-style string and "other"
+ */
 int String::compare(const String& other) const {
 	return strcmp(str, other.str);
 }
 
-char& String::operator[](unsigned index) {
-	return str[index];
-}
-
+/*!
+ * Uses the stream's getline function to read the data.
+ *
+ * \warning It takes at most 1024 characters from the stream!
+ * \note Best used with std::cin or text std::ifstream
+ */
 std::istream& operator>>(std::istream& istr, String& event) {
 	istr.getline(event.str, 1024);
 	event.length = strlen(event.str);
@@ -119,6 +154,11 @@ std::istream& operator>>(std::istream& istr, String& event) {
 	return istr;
 }
 
+/*!
+ * Uses the stream's << operator to write the underlying C-style string
+ *
+ * \note Best used with std::cout or text std::ofstream
+ */
 std::ostream& operator<<(std::ostream& ostr, const String& event) {
 	return ostr << event.str;
 }
diff --git a/src/Generic/String/String.h b/src/Generic/String/String.h
index 6a8b014..84fbe9c 100644
--- a/src/Generic/String/String.h
+++ b/src/Generic/String/String.h
@@ -1,6 +1,10 @@
 #ifndef HEADER_STRING
 #define HEADER_STRING
 
+/*! \file String.h
+ *  \brief Stores declaration of class String
+ */
+
 #include <istream>
 #include <ostream>
 
@@ -12,12 +16,20 @@ class String {
 	void copyFrom(const String& other);
 
 public:
+	//! The underlying array is allocated with length (+ 1) size
 	String(unsigned length);
+	//! Copies str
 	String(const char* str);
+	//! Returns internal C-style string
 	const char* get_cstr() const;
+	//! Returns number of characters in string
 	unsigned get_length() const;
+	//! Returns a character reference (from the underlying C-style string) at the given index
+	char& operator[](unsigned index);
 
+	//! Appends a C-style string
 	String& operator+=(const char* str);
+	//! Appends a number
 	String& operator+=(unsigned number);
 
 	String();
@@ -28,12 +40,16 @@ public:
 	String(String&& other);
 	String& operator=(String&& other);
 
+	//! Reads String from stream
 	void read(std::istream& istr);
+	//! Writes String to stream
 	void write(std::ostream& ostr) const;
+	//! Compares two strings
 	int compare(const String& other) const;
-	char& operator[](unsigned index);
 
+	//! Reads String from stream with >> operator
 	friend std::istream& operator>>(std::istream& istr, String& event);
+	//! Writes String to stream with << operator
 	friend std::ostream& operator<<(std::ostream& ostr, const String& event);
 };