From faad5bc2c8e7891eff009efeb0f03e917380f62e Mon Sep 17 00:00:00 2001
From: onyx-and-iris <code@onyxandiris.online>
Date: Tue, 2 Jul 2024 11:15:17 +0100
Subject: [PATCH] add doc comments

---
 README.md    |  2 +-
 src/util.c   | 13 +++++++++++++
 src/vmr.c    | 16 ++++++++++++++++
 src/vmrcli.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++++--
 4 files changed, 79 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index eb9e937..17fcb56 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@
 
 Where:
 
-- `h`: Prints the help dialogue.
+- `h`: Prints the help message.
 - `i`: Enable interactive mode. If set, any api commands passed on the command line will be ignored.
 - `k`: The kind of Voicemeeter (basic, banana or potato). Use this to launch the GUI.
 - `D`: Set log level 0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=FATAL
diff --git a/src/util.c b/src/util.c
index adf9d9f..7c46a16 100644
--- a/src/util.c
+++ b/src/util.c
@@ -3,6 +3,11 @@
 #include "vmr.h"
 #include "util.h"
 
+/**
+ * @brief Removes the last part of a path
+ *
+ * @param szPath
+ */
 void remove_name_in_path(char *szPath)
 {
     char *p = szPath;
@@ -57,6 +62,14 @@ int replace_multiple_space_with_one(char *s, size_t len)
     return j;
 }
 
+/**
+ * @brief
+ *
+ * @param s Pointer to a character buffer
+ * @param kind The kind of Voicemeeter.
+ * @param n maximum number of characters to be written to the buffer
+ * @return char* The kind of Voicemeeter as a string
+ */
 char *kind_as_string(char *s, enum kind kind, int n)
 {
     char *kinds[] = {
diff --git a/src/vmr.c b/src/vmr.c
index 4998193..16f00ec 100644
--- a/src/vmr.c
+++ b/src/vmr.c
@@ -8,6 +8,15 @@
 #define VERSION_STR_LEN 128
 #define KIND_STR_LEN 64
 
+/**
+ * @brief Logs into the API.
+ * Tests for valid connection for up to 2 seconds.
+ * If successful initializes the dirty parameters.
+ *
+ * @param vmr
+ * @param kind
+ * @return long
+ */
 long login(T_VBVMR_INTERFACE *vmr, int kind)
 {
     int rep;
@@ -45,6 +54,13 @@ long login(T_VBVMR_INTERFACE *vmr, int kind)
     return rep;
 }
 
+/**
+ * @brief Logs out of the API giving a short wait to allow a
+ * final instruction to complete.
+ *
+ * @param vmr The API interface as a struct
+ * @return long VBVMR_Logout return value
+ */
 long logout(T_VBVMR_INTERFACE *vmr)
 {
     int rep;
diff --git a/src/vmrcli.c b/src/vmrcli.c
index 214db7d..249f9ce 100644
--- a/src/vmrcli.c
+++ b/src/vmrcli.c
@@ -9,12 +9,21 @@
 
 #define MAX_LINE 512
 
+/**
+ * @brief An enum used to define the kind of value
+ * a 'get' call returns.
+ *
+ */
 enum
 {
     FLOAT_T,
     STRING_T,
 };
 
+/**
+ * @brief A struct holding the result of a get call.
+ *
+ */
 struct result
 {
     int type;
@@ -116,7 +125,7 @@ int main(int argc, char *argv[])
 }
 
 /**
- * @brief prints the help dialogue
+ * @brief prints the help message
  *
  */
 void help()
@@ -124,7 +133,7 @@ void help()
     puts(
         "Usage: ./vmrcli.exe [-h] [-i] [-k] [-D] [-v] <api commands>\n"
         "Where: \n"
-        "\th: Prints the help dialogue\n"
+        "\th: Prints the help message\n"
         "\ti: Enable interactive mode\n"
         "\tk: The kind of Voicemeeter (basic, banana, potato)\n"
         "\tD: Set log level 0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=FATAL\n"
@@ -167,6 +176,14 @@ enum kind set_kind(char *kval)
     }
 }
 
+/**
+ * @brief Defines the DLL interface as a struct.
+ * Logs into the API.
+ *
+ * @param vmr The API interface as a struct
+ * @param kind
+ * @return int
+ */
 int init_voicemeeter(T_VBVMR_INTERFACE *vmr, int kind)
 {
     int rep = initialize_dll_interfaces(vmr);
@@ -193,6 +210,13 @@ int init_voicemeeter(T_VBVMR_INTERFACE *vmr, int kind)
     return 0;
 }
 
+/**
+ * @brief Continuously read lines from stdin.
+ * Break if 'Q' is entered on the interactive prompt.
+ * Each line is passed to parse_input()
+ *
+ * @param vmr The API interface as a struct
+ */
 void interactive(T_VBVMR_INTERFACE *vmr)
 {
     char input[MAX_LINE];
@@ -213,6 +237,14 @@ void interactive(T_VBVMR_INTERFACE *vmr)
     }
 }
 
+/**
+ * @brief Walks through each line split by a space delimiter.
+ * Each token is passed to parse_command()
+ *
+ * @param vmr The API interface as a struct
+ * @param input Each input line, from stdin or CLI args
+ * @param len The length of the input line
+ */
 void parse_input(T_VBVMR_INTERFACE *vmr, char *input, int len)
 {
     char *token;
@@ -226,6 +258,14 @@ void parse_input(T_VBVMR_INTERFACE *vmr, char *input, int len)
     }
 }
 
+/**
+ * @brief Execute each command according to type.
+ * See command type definitions in:
+ * https://github.com/onyx-and-iris/vmrcli?tab=readme-ov-file#api-commands
+ *
+ * @param vmr The API interface as a struct
+ * @param command Each token from the input line as its own command string
+ */
 void parse_command(T_VBVMR_INTERFACE *vmr, char *command)
 {
     log_debug("Parsing %s", command);
@@ -279,6 +319,13 @@ void parse_command(T_VBVMR_INTERFACE *vmr, char *command)
     }
 }
 
+/**
+ * @brief
+ *
+ * @param vmr The API interface as a struct
+ * @param command A parsed 'get' command as a string
+ * @param res A struct holding the result of the API call.
+ */
 void get(T_VBVMR_INTERFACE *vmr, char *command, struct result *res)
 {
     clear_dirty(vmr);