Fully documented generic classes

2 files changed, 61 insertions, 5 deletions

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);
 };