Merge pull request #40 from jvdcf/Documentation

Documentation for Doxygen

main.cpp

@@ -1,4 +1,4 @@
-/*
+/**
  * @file main.cpp
  * @brief Point of entry of the program.
  */

src/CSVClasses.cpp

@@ -11,6 +11,7 @@
 
 /**
  * @brief This constructor receives a string containing all the lines of a csv file and creates the AppClass from it.
+ * Theoretical Complexity: O(n), n being the number of characters in a csv line.
  * @param csv
  */
 CSVClasses::CSVClasses(const std::string& csv) {

src/CSVStudentsClasses.cpp

@@ -13,7 +13,8 @@
 
 
 /**
- * This constructor receives a string containing all the lines of a csv file and creates the AppSudentClass from it.
+ * @brief This constructor receives a string containing all the lines of a csv file and creates the AppSudentClass from it.
+ * @details Theoretical Complexity: O(n), n being the number of characters in a csv line.
  * @param csv
  */
 CSVStudentsClasses::CSVStudentsClasses(const std::string& csv) {
@@ -42,7 +43,7 @@ CSVStudentsClasses::CSVStudentsClasses(const std::string& csv) {
 }
 
 /**
- * Erases the contents of students_classes.csv and saves there the updated values.
+ * @brief Erases the contents of students_classes.csv and saves there the updated values.
  */
 CSVStudentsClasses::~CSVStudentsClasses() {
     std::ofstream ofs;
@@ -63,6 +64,12 @@ CSVStudentsClasses::~CSVStudentsClasses() {
 }
 
 // Methods
+/**
+ * @brief Sort the entries vector by the category parameter.
+ * @details Available categories: UcCode, ClassCode, StudentCode, StudentName.
+ * Theoretical complexity: O(n log n), where n is the number of entries in the vector.
+ * @param category
+ */
 void CSVStudentsClasses::sort_by(const std::string& category) {
     if (category == "StudentCode") {
         std::stable_sort(this->entries.begin(), this->entries.end(),
@@ -92,6 +99,12 @@ void CSVStudentsClasses::sort_by(const std::string& category) {
     }
 }
 
+/**
+ * @deprecated
+ * @brief Search the lines for the first class with the given uc_code.
+ * @param uc_code
+ * @return Iterator to the first student with the given uc_code. If not found, returns a past-the-end pointer.
+ */
 std::vector<StudentsClasses>::iterator CSVStudentsClasses::search_by_uc(uint16_t uc_code) {
     sort_by(uc_cath_name);
     auto ret = entries.end();
@@ -117,6 +130,12 @@ std::vector<StudentsClasses>::iterator CSVStudentsClasses::search_by_uc(uint16_t
     }
 }
 
+/**
+ * @deprecated
+ * @brief Search the lines for the first class with the given student_code.
+ * @param student_code
+ * @return Iterator to the first class with the given student_code. If not found, returns a past-the-end pointer.
+ */
 std::vector<StudentsClasses>::iterator CSVStudentsClasses::search_by_student(uint32_t student_code) {
     sort_by(student_code_cath_name);
     auto ret = entries.end();
@@ -142,7 +161,12 @@ std::vector<StudentsClasses>::iterator CSVStudentsClasses::search_by_student(uin
     }
 }
 
-
+/**
+ * @deprecated
+ * @brief Search the lines for the first class with the given class_code.
+ * @param class_code
+ * @return Iterator to the first class with the given class_code. If not found, returns a past-the-end pointer.
+ */
 std::vector<StudentsClasses>::iterator CSVStudentsClasses::search_by_class(uint16_t class_code) {
     sort_by(class_cath_name);
     auto ret = entries.end();
@@ -169,6 +193,9 @@ std::vector<StudentsClasses>::iterator CSVStudentsClasses::search_by_class(uint1
 }
 
 // Debug
+/**
+ * @brief Displays the contents of the class.
+ */
 void CSVStudentsClasses::display() const {
     std::cout << this->student_code_cath_name << ','
               << this->student_name_cath_name << ','
@@ -178,5 +205,8 @@ void CSVStudentsClasses::display() const {
         e.display();
     }
 }
-
+/**
+ * @brief Getter for the vector of StudentsClasses.
+ * @return Pointer to entries
+ */
 std::vector<StudentsClasses> *CSVStudentsClasses::get_students() {return &this->entries;}

src/CSVStudentsClasses.hpp

@@ -7,13 +7,16 @@
 #include <string>
 #include <vector>
 
-
+/**
+ * @brief Representation of the file students_classes.csv
+ */
 class CSVStudentsClasses {
 private:
     std::string student_code_cath_name;
     std::string student_name_cath_name;
     std::string uc_cath_name;
     std::string class_cath_name;
+    /// Vector with every line of the file
     std::vector<StudentsClasses> entries;
 
 public:

src/ClassesPerUC.cpp

@@ -100,8 +100,8 @@ uint16_t ClassPerUC::parse_class(std::string class_code) {
 
 /**
  * @brief This method converts the attribute uc_code_ into a string and assigns the parameter out with its string value.
+ * Theoretical Complexity: O(1).
  * @param out
- * @tparam std::string
  */
 void ClassPerUC::uc_to_str(std::string &out) const {
     std::stringstream s;
@@ -119,8 +119,8 @@ void ClassPerUC::uc_to_str(std::string &out) const {
 
 /**
  * @brief This method converts the attribute class_code_ into a string and assigns the parameter out with its string value.
+ * Theoretical Complexity: O(1).
  * @param out
- * @tparam std::string
  */
 void ClassPerUC::class_to_str(std::string &out) const {
   std::stringstream s;
@@ -136,6 +136,7 @@ void ClassPerUC::class_to_str(std::string &out) const {
 
 /**
  * @brief This method prints the csv line of the current state of the object.
+ * Theoretical Complexity: O(1).
  */
 void ClassPerUC::display() const {
     // std::cout << "UcCode,ClassCode\n";

src/Lesson.cpp

@@ -8,7 +8,8 @@ using namespace std;
 
 
 /**
- * The constructor reads the line and assigns each string value to its attribute.
+ * @brief The constructor reads the line and assigns each string value to its attribute.
+ * Theoretical Complexity: O(n), n being the number of characters in a csv line.
  * @param line
  * @tparam std::string
  */
@@ -25,16 +26,38 @@ Lesson::Lesson(std::string line) {
 
 //______________________________________________________________________________________________________________________
 // Getters:
+/**
+ * @brief Getter for day.
+ * @return day
+ */
 WeekDay Lesson::get_day() const { return day; }
 
+/**
+ * @brief Getter for start_hour.
+ * @return start_hour
+ */
 double Lesson::get_start_hour() const { return start_hour; }
 
+/**
+ * @brief Getter for duration.
+ * @return duration
+ */
 double Lesson::get_duration() const { return duration; }
 
+/**
+ * @brief Getter for type
+ * @return type
+ */
 Type Lesson::get_type() const { return type; }
 
 //______________________________________________________________________________________________________________________
 // Parsers:
+/**
+ * @brief Parse day from a std::string to an WeekDay (enum).
+ * @details Useful to save memory and to make comparisons faster.
+ * @param day
+ * @return day as WeekDay
+ */
 WeekDay Lesson::parse_day(std::string day) {
   if (day == "Monday") {
     return WeekDay::MONDAY;
@@ -53,6 +76,12 @@ WeekDay Lesson::parse_day(std::string day) {
   }
 }
 
+/**
+ * @brief Parse type from a std::string to an Type (enum).
+ * @details Useful to save memory and to make comparisons faster.
+ * @param type
+ * @return type as Type
+ */
 Type Lesson::parse_type(std::string type) {
   if (type == "T") {
     return Type::T;
@@ -64,9 +93,8 @@ Type Lesson::parse_type(std::string type) {
 }
 
 /**
- * This method converts the attribute day into a string and assigns the parameter out with its string value.
+ * @brief This method converts the attribute day into a string and assigns the parameter out with its string value.
  * @param out
- * @tparam std::string
  */
 void Lesson::day_to_str(std::string &out) const {
   if (day == WeekDay::MONDAY) {
@@ -87,9 +115,8 @@ void Lesson::day_to_str(std::string &out) const {
 }
 
 /**
- * This method converts the attribute type into a string and assigns the parameter out with its string value.
+ * @brief This method converts the attribute type into a string and assigns the parameter out with its string value.
  * @param out
- * @tparam std::string
  */
 void Lesson::type_to_str(std::string &out) const {
   if (type == Type::T) {
@@ -104,7 +131,7 @@ void Lesson::type_to_str(std::string &out) const {
 //______________________________________________________________________________________________________________________
 // Other Methods:
 /**
- * This method prints the csv line of the current state of the object.
+ * @brief This method prints the csv line of the current state of the object.
  */
 void Lesson::display() const {
   string uc;

src/Lesson.hpp

@@ -37,11 +37,18 @@ enum class Type {
   PL,
 };
 
+/**
+ * @brief A lesson from a given class and a representation of one line inside the file classes.csv
+ */
 class Lesson : public ClassPerUC {
 private:
+  /// The day of the week the class takes place.
   WeekDay day;
+  /// The hour the class starts.
   float start_hour;
+  /// How long the class lasts.
   float duration;
+  /// The type of class: T, TP or PL.
   Type type;
 
 public:

src/Process.cpp

@@ -2,20 +2,40 @@
 #include <string>
 #include <vector>
 
-
+/**
+ * @brief Constructs a request of a certain type.
+ * This request is not yet completed, as the operands are still to be added.
+ * Theoretical Complexity: O(1).
+ * @param t
+ */
 Process::Process(TypeOfRequest t) {
   type = t;
   operands = std::vector<std::string>();
 }
 
+/**
+ * @brief Adds a string to the operands vector
+ * Theoretical Complexity: O(1).
+ * @param op
+ */
 void Process::add_operand(std::string op) {
   operands.push_back(op);
 }
 
+/**
+ * @brief Accesses the type of request.
+ * Theoretical Complexity: O(1).
+ * @return
+ */
 TypeOfRequest Process::get_type() {
   return type;
 }
 
+/**
+ * @brief Accesses the vector of operands.
+ * Theoretical Complexity: O(1).
+ * @return
+ */
 std::vector<std::string>& Process::get_ops() {
   return operands;
 }

src/Process.hpp

@@ -1,7 +1,9 @@
 #include <string>
 #include <vector>
 
-
+/**
+ * @brief Used to efficiently store the type of request.
+ */
 enum class TypeOfRequest {
   Add,
   Remove,
@@ -14,15 +16,22 @@ enum class TypeOfRequest {
   Batch,
 };
 
-
+/**
+ * @brief Stores the user requests.
+ */
 class Process {
-  private:
+private:
   TypeOfRequest type;
   std::vector<std::string> operands;
 
-  public:
+public:
+  // Costructor
   Process(TypeOfRequest t);
+
+  // Methods
   void add_operand(std::string s);
+
+  // Getters
   TypeOfRequest get_type();
   std::vector<std::string>& get_ops();
 };