From 06b9f25893f80d63fc74978c8a1621a33286de65 Mon Sep 17 00:00:00 2001
From: Patrick Lipka <patrick.lipka@emea.nec.com>
Date: Fri, 17 Dec 2021 12:05:13 +0100
Subject: [PATCH] cleanup done, more verbose comments added

---
 src/project.cpp      | 29 +++++++++++++++++++++++------
 src/string_utils.cpp |  4 ++++
 src/task.cpp         |  1 +
 src/track.cpp        |  5 +++++
 src/tt.cpp           |  5 +++++
 src/tt.h             |  2 ++
 src/ui.cpp           | 22 ++++++++++++++++------
 src/util.cpp         |  6 +++++-
 8 files changed, 61 insertions(+), 13 deletions(-)

diff --git a/src/project.cpp b/src/project.cpp
index 3f42c58..f6f2281 100644
--- a/src/project.cpp
+++ b/src/project.cpp
@@ -11,23 +11,27 @@ Project::Project(std::string name){
     Project::active_task = NULL;
 }
 
+// adds task to project
 void Project::add_task(Task task){
     tasks.push_back(task);
     set_active_task(num_tasks);
     num_tasks++;
 }
 
+// removes task from project by task id (position in tasks vector)
 void Project::remove_task(int id){
     tasks.erase(tasks.begin()+id);
     set_active_task(std::max(id-1,0));
     num_tasks--;
 }
 
+// sets active task pointer and id by task id (position in tasks vector)
 void Project::set_active_task(int id){
     active_task_id = id;
     active_task = &tasks[id];
 }
 
+// returns pointer to task with name task_name if present in tasks vector
 Task* Project::find_task_by_name(std::string task_name){
     for (int i=0; i<num_tasks; i++){
         if(tasks[i].name == task_name){
@@ -37,6 +41,7 @@ Task* Project::find_task_by_name(std::string task_name){
     return NULL;
 }
 
+// returns id of task with name task_name if present in tasks vector
 int Project::find_task_id_by_name(std::string task_name){
     for (int i=0; i<num_tasks; i++){
         if(tasks[i].name == task_name){
@@ -46,6 +51,7 @@ int Project::find_task_id_by_name(std::string task_name){
     return -1;
 }
 
+// returns sum of task work times in project
 int Project::get_total_work_time(){
    int wtime_proj = 0;
    for (int i=0; i<num_tasks; i++){
@@ -62,29 +68,31 @@ ProjectList::ProjectList(std::string month){
     ProjectList::num_projects = 0;
 }
 
+// adds project to project list
 void ProjectList::add_project(Project proj){
     projects.push_back(proj);
     set_active_project(num_projects);
     num_projects++;
 }
 
+// removes project from proects list by id (position in projects vector)
 void ProjectList::remove_project(int id){
     projects.erase(projects.begin()+id);
     set_active_project(std::max(id-1,0));
     num_projects--;
 }
 
+// sets active project pointer and id by id (position in projects vector)
 void ProjectList::set_active_project(int id){
     active_project_id = id;
     active_project = &projects[id];
 }
 
-
+// serializes project list and writes it to binary file
 void ProjectList::save(std::string file_name){
     std::ofstream of(file_name, std::ios::binary);
     if (!of){
         std::cout << "Could not open file " << file_name << " for writing!" << std::endl;
-       // exit(1);
     }
     of.write((char*) &num_projects, sizeof(int));
     of.write((char*) &active_project_id, sizeof(int));
@@ -104,6 +112,7 @@ void ProjectList::save(std::string file_name){
     of.close();
 }
 
+// reads project list from binary file
 void ProjectList::load(std::string file_name, bool ignore_worktimes){
     std::ifstream inf(file_name, std::ios::binary);
     int active;
@@ -111,11 +120,16 @@ void ProjectList::load(std::string file_name, bool ignore_worktimes){
         std::cout << "Could not open file " << file_name << " for reading!" << std::endl;
     }
     inf.read((char*) &num_projects,sizeof(int));
+    // save copy of num_projects to control loop and apply later as
+    // num_projects will get bigger when adding projects to the project list
     int number_of_projects = num_projects;
     inf.read((char*) &active, sizeof(int));
-    int np = num_projects;
-    int *active_task_arr = new int[np];
-    for (int i=0; i<np;i++){
+    // build active task array to set active tasks once 
+    // project list is set up to get the poiters right
+    int *active_task_arr = new int[number_of_projects];
+    
+    // read project properties
+    for (int i=0; i<number_of_projects; i++){
         size_t len;
         std::string proj_name;
         int active_t;
@@ -130,6 +144,7 @@ void ProjectList::load(std::string file_name, bool ignore_worktimes){
         int number_of_tasks = proj.num_tasks;
         inf.read((char*) &active_t, sizeof(int));
         int nt = proj.num_tasks;
+        // read task properties
         for (int j=0; j<nt; j++){
             std::string task_name;
             size_t task_name_len;
@@ -151,7 +166,7 @@ void ProjectList::load(std::string file_name, bool ignore_worktimes){
         add_project(proj);
     }
     set_active_project(active);
-    for (int i=0; i<np ; i++){
+    for (int i=0; i<number_of_projects ; i++){
         projects[i].set_active_task(active_task_arr[i]);
     }
     delete [] active_task_arr;
@@ -159,6 +174,7 @@ void ProjectList::load(std::string file_name, bool ignore_worktimes){
     num_projects = number_of_projects;
 }
 
+// returns pointer to project with name proj_name if present in projects vector
 Project* ProjectList::find_project_by_name(std::string proj_name){
     for (int i=0; i<num_projects; i++){
         if(projects[i].name == proj_name){
@@ -168,6 +184,7 @@ Project* ProjectList::find_project_by_name(std::string proj_name){
     return NULL;
 }
 
+// returns id of project with name proj_name is present in projects vector
 int ProjectList::find_project_id_by_name(std::string proj_name){
     for (int i=0; i<num_projects; i++){
         if(projects[i].name == proj_name){
diff --git a/src/string_utils.cpp b/src/string_utils.cpp
index 61db341..00e0f47 100644
--- a/src/string_utils.cpp
+++ b/src/string_utils.cpp
@@ -1,6 +1,7 @@
 #include <string>
 #include "string_utils.h"
 
+// replaces white spaces by underscores, used for readline completion
 std::string space_to_underscore(std::string str){
     for(size_t i = 0; i < str.length(); i++){
         if(str[i] == ' ') str[i] = '_';
@@ -8,6 +9,7 @@ std::string space_to_underscore(std::string str){
     return str;
 }
 
+// replaces underscores by white space, used to translate readline completion to real names
 std::string underscore_to_space(std::string str){
     for(size_t i = 0; i < str.length(); i++){
         if(str[i] == '_') str[i] = ' ';
@@ -15,6 +17,7 @@ std::string underscore_to_space(std::string str){
     return str;
 }
 
+// remove trailing and leading white spaces from string
 std::string trim(const std::string& str){
     const char* WhiteSpace = " ";
     std::size_t start = str.find_first_not_of(WhiteSpace);
@@ -22,6 +25,7 @@ std::string trim(const std::string& str){
     return start == end ? std::string() : str.substr(start, end - start + 1);
 }
 
+// check whether string is a number
 bool is_num(const std::string &str){
     for (const char &c : str){
         if (std::isdigit(c) == 0) return false;
diff --git a/src/task.cpp b/src/task.cpp
index a92a32d..076d4f5 100644
--- a/src/task.cpp
+++ b/src/task.cpp
@@ -7,6 +7,7 @@ Task::Task(std::string name){
     Task::work_time = 0;
 }
 
+// add working time, also used to remove working time with negative input values
 void Task::add_time(int seconds){
     work_time = std::max(work_time+seconds,0); 
 }
diff --git a/src/track.cpp b/src/track.cpp
index aaab810..b7a1029 100644
--- a/src/track.cpp
+++ b/src/track.cpp
@@ -6,7 +6,10 @@
 int sigint;
 int tracking;
 
+// signal handler to execute when receiving SIGINT (CTRL-C)
 void handler(int signum){
+    // while tracking: end tracking and continue execution
+    // else: exit program
     if (tracking){
         sigint = 1;
         std::cout << std::endl;
@@ -15,10 +18,12 @@ void handler(int signum){
     }
 }
 
+// track time for active task in project
 void track(Project *proj){
     int worktime = 0;
     int work_h, work_m, work_s;
     time_t start;
+    // clear terminal
     system("clear");
     time(&start);
     tracking = 1;
diff --git a/src/tt.cpp b/src/tt.cpp
index fbf41a1..68868ca 100644
--- a/src/tt.cpp
+++ b/src/tt.cpp
@@ -13,16 +13,20 @@
 #include "tt.h"
 #include "util.h"
 
+// glovbal variables:
 std::string user_name, tracking_dir, config_file;
 
 int main(){ 
     // connect SIGINT signal (CTRL-C) to signal handler from track.h to use it to stop tracking of projects
     signal(SIGINT, handler);
     tracking = 0;
+
+    // PREFIX set by preprocessor, see Makefile
     std::string prefix=STRING(PREFIX);
     config_file = prefix+"/etc/tt.conf";
     parse_config_file(config_file, &user_name, &tracking_dir);    
     
+    // initialize project list for current month
     ProjectList proj_list(get_date());
     
     // if available: load project list for current month, else: start with list from last month
@@ -41,6 +45,7 @@ int main(){
         proj_list.load(last_proj_file,true);
     }
 
+    // add command names and names of project list to the autocomplete names
     init_autocomplete(&proj_list);
 
     // use GNU readline for auto completion and history when parsing command input
diff --git a/src/tt.h b/src/tt.h
index a1e92d2..0ab361c 100644
--- a/src/tt.h
+++ b/src/tt.h
@@ -2,6 +2,8 @@
 #define TT_H
 
 #include <string>
+
+// global variables:
 extern std::string user_name;
 extern std::string tracking_dir;
 extern std::string config_file;
diff --git a/src/ui.cpp b/src/ui.cpp
index a9fbbea..4b431ca 100644
--- a/src/ui.cpp
+++ b/src/ui.cpp
@@ -15,8 +15,7 @@
 #include "tt.h"
 #include "util.h"
 
-// Uses GNU readline library for autocompletion and command history
-
+// names of available commands
 std::string command_names[num_commands]={
     "np",
     "nt",
@@ -32,12 +31,15 @@ std::string command_names[num_commands]={
     "save"
 };
 
-std::vector<std::string> autocomplete_names;
+std::vector<std::string> autocomplete_names; // global variable
+
+// completion function for readline
 char **tt_name_completion(const char* text, int start, int end){
     rl_attempted_completion_over = 1;
     return rl_completion_matches(text, tt_name_generator);
 }
 
+// search for input in auto complete names to attempt completion and give options
 char *tt_name_generator(const char *text, int state){
      static std::vector<std::string>::const_iterator it;
      if (state == 0) it=begin(autocomplete_names);
@@ -51,6 +53,7 @@ char *tt_name_generator(const char *text, int state){
      return NULL;
 }
 
+// add command and project/task names to auto complete list
 void init_autocomplete(ProjectList *proj_list){
     // add command names to auto complete list
     for (int i=0; i<num_commands; i++){
@@ -68,6 +71,7 @@ void init_autocomplete(ProjectList *proj_list){
     }
 }
 
+// parse user input and call appropriate commad_* functions 
 void parse_input(std::string input, ProjectList *proj_list){
     input = trim(input);
     size_t command_end = input.find(" ");
@@ -158,8 +162,7 @@ void parse_input(std::string input, ProjectList *proj_list){
                     command_rt(task_name,stoi(wtime_str),proj_list);
                 }else{
                     std::cout << "remove time: please specify time to remove and task name [optional]." << std::endl;
-                }
-                                                                                                                
+                }                                                                                       
             }
         }
     }else if (command == "report"){
@@ -262,6 +265,7 @@ void command_rm(std::string input, ProjectList *proj_list){
     }
     bool del = false;
     if (place_of_slash == std::string::npos && id >= 0){
+        // do not let the user remove projects by accident
         std::cout << "Do you really want to remove project " << underscore_to_space(proj_name) << "? [y|n]" << std::endl;
         std::string input;
         while(1){
@@ -302,6 +306,7 @@ void command_rm(std::string input, ProjectList *proj_list){
         int task_id = proj_list->active_project->find_task_id_by_name(trim(underscore_to_space(task_name)));
         if (task_id >=0){
             del = false;
+            // do not let the user remove tasks by accident
             std::cout << "Do you really want to remove task " << underscore_to_space(proj->name) << "/" << underscore_to_space(task_name) << "? [y|n]" << std::endl;
             std::string input;
             while(1){
@@ -383,6 +388,7 @@ void command_st(std::string input, ProjectList *proj_list){
    int proj_id = proj_list->find_project_id_by_name(trim(underscore_to_space(proj_name)));
    Project *proj = proj_list->find_project_by_name(trim(underscore_to_space(proj_name)));
    if (place_of_slash == std::string::npos){
+        // task in same project
         proj = proj_list->active_project;
         proj_id = proj_list->find_project_id_by_name(trim(underscore_to_space(proj_list->active_project->name)));
    }
@@ -540,6 +546,7 @@ void command_rt(std::string input, int wtime, ProjectList *proj_list){
     }
 }
 
+// print monthly report 
 void command_report(std::string date_str, ProjectList* proj_list){
     date_str = trim(date_str);
     size_t place_of_minus = date_str.find("-");
@@ -561,6 +568,7 @@ void command_report(std::string date_str, ProjectList* proj_list){
                     float wtime_task = proj->tasks[j].work_time / 3600.0;
                     if(wtime_task >= 0.01) std::cout << "--- " << proj->tasks[j].name << ": " << std::fixed << std::setprecision(2) << wtime_task << std::endl;
                 }
+                // format: *.xx hours
                 std::cout << "Total: " << std::fixed << std::setprecision(2) << wtime_proj << std::endl << std::endl;
             }
         }
@@ -580,6 +588,7 @@ void command_report(std::string date_str, ProjectList* proj_list){
                         float wtime_task = proj->tasks[j].work_time / 3600.0;
                         if(wtime_task >= 0.01) std::cout << "--- " << proj->tasks[j].name << ": " << std::fixed << std::setprecision(2) << wtime_task << std::endl;
                     }
+                    // format: *.xx hours
                     std::cout << "Total: " << std::fixed << std::setprecision(2) << wtime_proj << std::endl << std::endl;
                 }
             }
@@ -589,7 +598,8 @@ void command_report(std::string date_str, ProjectList* proj_list){
     }
 }
 
-// save project list to file - POSIX only
+// save project list to file, uses system("mkdir") to create diretory
+// might be replaced by C++ filesystem API int the future
 void command_save(ProjectList *proj_list){
     std::string date_str = get_date();
     std::string file_name = tracking_dir+"/"+date_str;
diff --git a/src/util.cpp b/src/util.cpp
index 166a6d0..d23180d 100644
--- a/src/util.cpp
+++ b/src/util.cpp
@@ -2,6 +2,7 @@
 #include <iostream>
 #include "util.h"
 
+// returns string in format "yyyy-mm"
 std::string get_date(){
     time_t t = time(NULL);
     tm *date = localtime(&t);
@@ -17,12 +18,14 @@ std::string get_date(){
     return date_str;
 }
 
+// returns date string for previous month
 std::string get_last_date(){
     time_t t = time(NULL);
     tm *date = localtime(&t);
     int month = date->tm_mon;
     int year = date->tm_year+1900;
-
+    
+    // in case of January:
     if(month == 0){
         month = 12;
         year--;
@@ -38,6 +41,7 @@ std::string get_last_date(){
     return date_str;
 }
 
+// basic parsing of configureation file to get user name and tracking directory
 void parse_config_file(std::string file_name, std::string *user_name, std::string *tracking_dir){
     std::ifstream f(file_name);
     if (!f){