From 774c89cbfd58e801316a5e97f4ac9881df69c8a2 Mon Sep 17 00:00:00 2001
From: Robin Jones <networkfusion@users.noreply.github.com>
Date: Sat, 22 Feb 2025 00:26:39 +0000
Subject: [PATCH] Fix favorites load (count)

and documentation
---
 src/menu/bookkeeping.c | 147 ++++++++++++++++++++++++++++++++---------
 1 file changed, 116 insertions(+), 31 deletions(-)

diff --git a/src/menu/bookkeeping.c b/src/menu/bookkeeping.c
index bbdbcc3f..82808266 100644
--- a/src/menu/bookkeeping.c
+++ b/src/menu/bookkeeping.c
@@ -1,3 +1,9 @@
+/**
+ * @file bookkeeping.c
+ * @brief Bookkeeping functions for history and favorites
+ * @ingroup menu
+ */
+
 #include <libdragon.h>
 #include <mini.c/src/mini.h>
 
@@ -6,11 +12,14 @@
 #include "path.h"
 
 static char *history_path = NULL;
-
 static path_t *empty_path = NULL;
 static bookkeeping_t init;
 
-/** @brief Init history path */
+/**
+ * @brief Initialize the bookkeeping system with the specified path.
+ * 
+ * @param path Path to the history file.
+ */
 void bookkeeping_init (char *path) {
     if (history_path) {
         free(history_path);
@@ -19,23 +28,33 @@ void bookkeeping_init (char *path) {
     empty_path = path_create("");
 }
 
-
-void bookkeeping_ini_load_list(bookkeeping_item_t *list, int count, mini_t *ini, const char *group)
-{
+/**
+ * @brief Load a list of bookkeeping items from an INI file.
+ * 
+ * @param list Pointer to the list of bookkeeping items.
+ * @param count Number of items in the list.
+ * @param ini Pointer to the INI file structure.
+ * @param group Name of the group in the INI file.
+ */
+void bookkeeping_ini_load_list(bookkeeping_item_t *list, int count, mini_t *ini, const char *group) {
     char buf[64];
-    for(int i=0; i<count; i++) {
-        sprintf(buf,"%d_primary_path", i);
+    for(int i = 0; i < count; i++) {
+        sprintf(buf, "%d_primary_path", i);
         list[i].primary_path = path_create(mini_get_string(ini, group, buf, ""));
 
-        sprintf(buf,"%d_secondary_path", i);
+        sprintf(buf, "%d_secondary_path", i);
         list[i].secondary_path = path_create(mini_get_string(ini, group, buf, ""));
         
-        sprintf(buf,"%d_type", i);
+        sprintf(buf, "%d_type", i);
         list[i].bookkeeping_type = mini_get_int(ini, group, buf, BOOKKEEPING_TYPE_EMPTY);
     }
 }
 
-/** @brief The history to load */
+/**
+ * @brief Load the bookkeeping history and favorites from the history file.
+ * 
+ * @param history Pointer to the bookkeeping structure.
+ */
 void bookkeeping_load (bookkeeping_t *history) {
     if (!file_exists(history_path)) {
         bookkeeping_save(&init);
@@ -43,16 +62,22 @@ void bookkeeping_load (bookkeeping_t *history) {
 
     mini_t *bookkeeping_ini = mini_try_load(history_path);
     bookkeeping_ini_load_list(history->history_items, HISTORY_COUNT, bookkeeping_ini, "history");
-    bookkeeping_ini_load_list(history->favorite_items, HISTORY_COUNT, bookkeeping_ini, "favorite");
-
+    bookkeeping_ini_load_list(history->favorite_items, FAVORITES_COUNT, bookkeeping_ini, "favorite");
 
     mini_free(bookkeeping_ini);
 }
 
-static void bookkeeping_ini_save_list(bookkeeping_item_t *list, int count, mini_t *ini, const char *group)
-{
+/**
+ * @brief Save a list of bookkeeping items to an INI file.
+ * 
+ * @param list Pointer to the list of bookkeeping items.
+ * @param count Number of items in the list.
+ * @param ini Pointer to the INI file structure.
+ * @param group Name of the group in the INI file.
+ */
+static void bookkeeping_ini_save_list(bookkeeping_item_t *list, int count, mini_t *ini, const char *group) {
     char buf[64];
-    for(int i=0; i<count; i++) {
+    for(int i = 0; i < count; i++) {
         sprintf(buf, "%d_primary_path", i);
         path_t* path = list[i].primary_path;
         mini_set_string(ini, group, buf, path != NULL ? path_get(path) : "");   
@@ -61,14 +86,17 @@ static void bookkeeping_ini_save_list(bookkeeping_item_t *list, int count, mini_
         path = list[i].secondary_path;
         mini_set_string(ini, group, buf, path != NULL ? path_get(path) : "");   
 
-        sprintf(buf,"%d_type", i);
+        sprintf(buf, "%d_type", i);
         mini_set_int(ini, group, buf, list[i].bookkeeping_type);           
     }
 }
 
-/** @brief The history to save */
-void bookkeeping_save (bookkeeping_t *history)
-{
+/**
+ * @brief Save the bookkeeping history and favorites to the history file.
+ * 
+ * @param history Pointer to the bookkeeping structure.
+ */
+void bookkeeping_save (bookkeeping_t *history) {
     mini_t *bookkeeping_ini = mini_create(history_path);
 
     bookkeeping_ini_save_list(history->history_items, HISTORY_COUNT, bookkeeping_ini, "history");
@@ -78,6 +106,13 @@ void bookkeeping_save (bookkeeping_t *history)
     mini_free(bookkeeping_ini);    
 }
 
+/**
+ * @brief Check if two bookkeeping items match.
+ * 
+ * @param left Pointer to the first bookkeeping item.
+ * @param right Pointer to the second bookkeeping item.
+ * @return true if the items match, false otherwise.
+ */
 static bool bookkeeping_item_match(bookkeeping_item_t *left, bookkeeping_item_t *right) {
     if(left != NULL && right != NULL) {
         return path_are_match(left->primary_path, right->primary_path) && path_are_match(left->secondary_path, right->secondary_path) && left->bookkeeping_type == right->bookkeeping_type;
@@ -86,6 +121,12 @@ static bool bookkeeping_item_match(bookkeeping_item_t *left, bookkeeping_item_t
     return false;
 }
 
+/**
+ * @brief Clear a bookkeeping item.
+ * 
+ * @param item Pointer to the bookkeeping item.
+ * @param leave_null Flag indicating whether to leave the paths as NULL.
+ */
 static void bookkeeping_clear_item(bookkeeping_item_t *item, bool leave_null) {
     if(item->primary_path != NULL){
         path_free(item->primary_path);
@@ -108,6 +149,12 @@ static void bookkeeping_clear_item(bookkeeping_item_t *item, bool leave_null) {
     item->bookkeeping_type = BOOKKEEPING_TYPE_EMPTY;
 }
 
+/**
+ * @brief Copy a bookkeeping item.
+ * 
+ * @param source Pointer to the source bookkeeping item.
+ * @param destination Pointer to the destination bookkeeping item.
+ */
 static void bookkeeping_copy_item(bookkeeping_item_t *source, bookkeeping_item_t *destination) {
     bookkeeping_clear_item(destination, true);
 
@@ -116,6 +163,13 @@ static void bookkeeping_copy_item(bookkeeping_item_t *source, bookkeeping_item_t
     destination->bookkeeping_type = source->bookkeeping_type;
 }
 
+/**
+ * @brief Move bookkeeping items down in the list.
+ * 
+ * @param list Pointer to the list of bookkeeping items.
+ * @param start Start index.
+ * @param end End index.
+ */
 static void bookkeeping_move_items_down(bookkeeping_item_t *list, int start, int end) {
     int current = end;
 
@@ -129,7 +183,13 @@ static void bookkeeping_move_items_down(bookkeeping_item_t *list, int start, int
     } while(true);
 }
 
-
+/**
+ * @brief Move bookkeeping items up in the list.
+ * 
+ * @param list Pointer to the list of bookkeeping items.
+ * @param start Start index.
+ * @param end End index.
+ */
 static void bookkeeping_move_items_up(bookkeeping_item_t *list, int start, int end) {
     int current = start;
 
@@ -143,7 +203,13 @@ static void bookkeeping_move_items_up(bookkeeping_item_t *list, int start, int e
     } while(true);
 }
 
-
+/**
+ * @brief Insert a bookkeeping item at the top of the list.
+ * 
+ * @param list Pointer to the list of bookkeeping items.
+ * @param count Number of items in the list.
+ * @param new_item Pointer to the new bookkeeping item.
+ */
 static void bookkeeping_insert_top(bookkeeping_item_t *list, int count, bookkeeping_item_t *new_item) {
     // if it matches the top of the list already then nothing to do
     if(bookkeeping_item_match(&list[0], new_item)) {
@@ -153,7 +219,7 @@ static void bookkeeping_insert_top(bookkeeping_item_t *list, int count, bookkeep
     // if the top isn't empty then we need to move things around
     if(list[0].bookkeeping_type != BOOKKEEPING_TYPE_EMPTY) {
         int found_at = -1;
-        for(int i=1; i < count; i++) {
+        for(int i = 1; i < count; i++) {
             if(bookkeeping_item_match(&list[i], new_item)){
                 found_at = i;
                 break;
@@ -170,35 +236,54 @@ static void bookkeeping_insert_top(bookkeeping_item_t *list, int count, bookkeep
     bookkeeping_copy_item(new_item, &list[0]);
 }
 
-void bookkeeping_history_add(bookkeeping_t *bookkeeping, path_t *primary_path, path_t *secondary_path, bookkeeping_item_types_t type ) {
+/**
+ * @brief Add a new item to the bookkeeping history.
+ * 
+ * @param bookkeeping Pointer to the bookkeeping structure.
+ * @param primary_path Pointer to the primary path.
+ * @param secondary_path Pointer to the secondary path.
+ * @param type The type of the bookkeeping item.
+ */
+void bookkeeping_history_add(bookkeeping_t *bookkeeping, path_t *primary_path, path_t *secondary_path, bookkeeping_item_types_t type) {
     bookkeeping_item_t new_item = {
         .primary_path = primary_path,
         .secondary_path = secondary_path,
         .bookkeeping_type = type
     };
 
-    bookkeeping_insert_top(bookkeeping->history_items, HISTORY_COUNT,  &new_item);
+    bookkeeping_insert_top(bookkeeping->history_items, HISTORY_COUNT, &new_item);
     bookkeeping_save(bookkeeping);
 }
 
-
-void bookkeeping_favorite_add(bookkeeping_t *bookkeeping, path_t *primary_path, path_t *secondary_path, bookkeeping_item_types_t type ) {
+/**
+ * @brief Add a new item to the bookkeeping favorites.
+ * 
+ * @param bookkeeping Pointer to the bookkeeping structure.
+ * @param primary_path Pointer to the primary path.
+ * @param secondary_path Pointer to the secondary path.
+ * @param type The type of the bookkeeping item.
+ */
+void bookkeeping_favorite_add(bookkeeping_t *bookkeeping, path_t *primary_path, path_t *secondary_path, bookkeeping_item_types_t type) {
     bookkeeping_item_t new_item = {
         .primary_path = primary_path,
         .secondary_path = secondary_path,
         .bookkeeping_type = type
     };
 
-    bookkeeping_insert_top(bookkeeping->favorite_items, FAVORITES_COUNT,  &new_item);
+    bookkeeping_insert_top(bookkeeping->favorite_items, FAVORITES_COUNT, &new_item);
     bookkeeping_save(bookkeeping);
 }
 
+/**
+ * @brief Remove an item from the bookkeeping favorites.
+ * 
+ * @param bookkeeping Pointer to the bookkeeping structure.
+ * @param selection Index of the item to remove.
+ */
 void bookkeeping_favorite_remove(bookkeeping_t *bookkeeping, int selection) {
     if(bookkeeping->favorite_items[selection].bookkeeping_type != BOOKKEEPING_TYPE_EMPTY) {
-
-        bookkeeping_move_items_up(bookkeeping->favorite_items, selection, FAVORITES_COUNT -1);
-        bookkeeping_clear_item(&bookkeeping->favorite_items[FAVORITES_COUNT -1], false);
-
+        bookkeeping_move_items_up(bookkeeping->favorite_items, selection, FAVORITES_COUNT - 1);
+        bookkeeping_clear_item(&bookkeeping->favorite_items[FAVORITES_COUNT - 1], false);
         bookkeeping_save(bookkeeping);
     }
 }
\ No newline at end of file