From c0f6b7c7ee27ec8056c39ac5f8afebc847f8a2da Mon Sep 17 00:00:00 2001
From: Kevin Day <kevin@kevux.org>
Date: Tue, 20 Feb 2024 21:37:38 -0600
Subject: [PATCH] Cleanup: Function documentation comments, removing or fixing
 invalid comments.

The Doxygen wizard reported warnings that exposed these problems.
---
 level_0/f_capability/c/capability.h         |  3 --
 level_0/f_console/c/console.h               |  4 +--
 level_0/f_environment/c/environment.h       |  6 +---
 level_0/f_fss/c/fss.h                       |  8 -----
 level_0/f_iki/c/iki/data.h                  | 48 ++++++++++++++---------------
 level_0/f_print/c/print.h                   |  2 --
 level_0/f_string/c/string/static.h          |  2 +-
 level_0/f_thread/c/thread.h                 |  4 ++-
 level_1/fl_control_group/c/control_group.h  |  2 +-
 level_1/fl_print/c/print.h                  |  2 --
 level_1/fl_string/c/string.h                |  2 ++
 level_1/fl_utf_file/c/utf_file.h            |  4 +--
 level_2/fll_control_group/c/control_group.h |  2 +-
 level_2/fll_print/c/print.h                 |  2 --
 14 files changed, 37 insertions(+), 54 deletions(-)

diff --git a/level_0/f_capability/c/capability.h b/level_0/f_capability/c/capability.h
index 2efaa1d..4c97d18 100644
--- a/level_0/f_capability/c/capability.h
+++ b/level_0/f_capability/c/capability.h
@@ -892,9 +892,6 @@ extern "C" {
 /**
  * Check if capabilities support ambient, using special libcap function/macro.
  *
- * @param code
- *   The capability code.
- *
  * @return
  *   TRUE if ambient is supported.
  *   FALSE otherwise.
diff --git a/level_0/f_console/c/console.h b/level_0/f_console/c/console.h
index 04319b9..c6c2681 100644
--- a/level_0/f_console/c/console.h
+++ b/level_0/f_console/c/console.h
@@ -33,8 +33,8 @@ extern "C" {
  *
  * All values are appended to the environment maps.
  *
- * @param parameters
- *   The parameters to process.
+ * @param arguments
+ *   The arguments to process.
  * @param environment
  *   Maps representing the environment variable names and values.
  *   Both the name and the value strings may not be NULL terminated.
diff --git a/level_0/f_environment/c/environment.h b/level_0/f_environment/c/environment.h
index e00fcf1..edc9ca8 100644
--- a/level_0/f_environment/c/environment.h
+++ b/level_0/f_environment/c/environment.h
@@ -52,13 +52,9 @@ extern "C" {
  * The variable is copied into a new dynamically allocated string and is safe to alter.
  *
  * @param name
- *   The name of the environment variable to get.
+ *   The name of the environment variable to check the existence of.
  *   The name string must not contain the '=' character.
  *   The name must be NULL terminated.
- * @param value
- *   The value associated with name.
- *   The value will not be null terminated.
- *   The value will be appended (set value->used to 0 to replace).
  *
  * @return
  *   F_data_not if name.used is 0.
diff --git a/level_0/f_fss/c/fss.h b/level_0/f_fss/c/fss.h
index 2ab5339..2ec2e32 100644
--- a/level_0/f_fss/c/fss.h
+++ b/level_0/f_fss/c/fss.h
@@ -198,8 +198,6 @@ extern "C" {
  *   The string to process.
  * @param range
  *   The character at the start position will be checked against the graph.
- * @param header
- *   The header data to populate with results of this function.
  *
  * @return
  *   F_true if the character in the buffer is a combining character.
@@ -224,8 +222,6 @@ extern "C" {
  *   The string to process.
  * @param range
  *   The character at the start position will be checked against the graph.
- * @param header
- *   The header data to populate with results of this function.
  *
  * @return
  *   F_true if the character in the buffer is a graph character.
@@ -250,8 +246,6 @@ extern "C" {
  *   The string to process.
  * @param range
  *   The character at the start position will be checked against the graph.
- * @param header
- *   The header data to populate with results of this function.
  *
  * @return
  *   F_true if the character in the buffer is a space character.
@@ -282,8 +276,6 @@ extern "C" {
  *   The string to process.
  * @param range
  *   The character at the start position will be checked against the graph.
- * @param header
- *   The header data to populate with results of this function.
  *
  * @return
  *   F_true if the character in the buffer is a zero-width character.
diff --git a/level_0/f_iki/c/iki/data.h b/level_0/f_iki/c/iki/data.h
index 4c1b004..a74e50d 100644
--- a/level_0/f_iki/c/iki/data.h
+++ b/level_0/f_iki/c/iki/data.h
@@ -63,8 +63,8 @@ extern "C" {
  *
  * @param length
  *   The new size to use.
- * @param iki_datas
- *   The iki_datas array to resize.
+ * @param datas
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -126,8 +126,8 @@ extern "C" {
  *
  * @param amount
  *   A positive number representing how much to decimate the size by.
- * @param iki_datas
- *   The iki_datas array to resize.
+ * @param datas
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -150,8 +150,8 @@ extern "C" {
  *
  * @param amount
  *   A positive number representing how much to decrease the size by.
- * @param iki_datas
- *   The iki_datas array to resize.
+ * @param datas
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -174,8 +174,8 @@ extern "C" {
  * @param step
  *   The allocation step to use.
  *   Must be greater than 0.
- * @param iki_datas
- *   The iki_datas array to resize.
+ * @param datas
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -199,8 +199,8 @@ extern "C" {
  *
  * @param amount
  *   A positive number representing how much to increase the size by.
- * @param iki_datas
- *   The iki_datas array to resize.
+ * @param datas
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -220,8 +220,8 @@ extern "C" {
  *
  * @param length
  *   The new size to use.
- * @param iki_datas
- *   The iki_datas array to adjust.
+ * @param datas
+ *   The array to adjust.
  *
  * @return
  *   F_none on success.
@@ -239,8 +239,8 @@ extern "C" {
  *
  * @param length
  *   The new size to use.
- * @param iki_datass
- *   The iki_datass array to resize.
+ * @param datass
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -303,8 +303,8 @@ extern "C" {
  *
  * @param amount
  *   A positive number representing how much to decimate the size by.
- * @param iki_datass
- *   The iki_datass array to resize.
+ * @param datass
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -328,8 +328,8 @@ extern "C" {
  *
  * @param amount
  *   A positive number representing how much to decrease the size by.
- * @param iki_datass
- *   The iki_datass array to resize.
+ * @param datass
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -353,8 +353,8 @@ extern "C" {
  * @param step
  *   The allocation step to use.
  *   Must be greater than 0.
- * @param iki_datass
- *   The iki_datass array to resize.
+ * @param datass
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -378,8 +378,8 @@ extern "C" {
  *
  * @param amount
  *   A positive number representing how much to increase the size by.
- * @param iki_datass
- *   The iki_datass array to resize.
+ * @param datass
+ *   The array to resize.
  *
  * @return
  *   F_none on success.
@@ -399,8 +399,8 @@ extern "C" {
  *
  * @param length
  *   The new size to use.
- * @param iki_datass
- *   The iki_datass array to adjust.
+ * @param datass
+ *   The array to adjust.
  *
  * @return
  *   F_none on success.
diff --git a/level_0/f_print/c/print.h b/level_0/f_print/c/print.h
index 5a4bbca..ade3bf6 100644
--- a/level_0/f_print/c/print.h
+++ b/level_0/f_print/c/print.h
@@ -1576,8 +1576,6 @@ extern "C" {
  *
  * @param string
  *   The string to output.
- * @param length
- *   The total number of characters to print.
  * @param stream
  *   The file stream to output to, including standard streams such as stdout and stderr.
  *
diff --git a/level_0/f_string/c/string/static.h b/level_0/f_string/c/string/static.h
index 68d5c0c..31a90c2 100644
--- a/level_0/f_string/c/string/static.h
+++ b/level_0/f_string/c/string/static.h
@@ -545,7 +545,7 @@ extern "C" {
 
 /**
  * Define the end of line character.
- * FLL forbids '\r' and '\r\n' as end of line characters, \r will be silently ignored.
+ * FLL forbids '\r' and '\r\n' as end of line characters, '\r' will be silently ignored.
  */
 #ifndef _di_f_string_eol_s_
   #define f_string_eol_s f_string_ascii_feed_line_s
diff --git a/level_0/f_thread/c/thread.h b/level_0/f_thread/c/thread.h
index 88e539d..03f7f84 100644
--- a/level_0/f_thread/c/thread.h
+++ b/level_0/f_thread/c/thread.h
@@ -58,7 +58,7 @@ extern "C" {
  *   The function to call before forking.
  * @param after_parent
  *   The function called after forking, for the parent process.
- * @param child_parent
+ * @param after_child
  *   The function called after forking, for the child process.
  *
  * @return
@@ -2101,6 +2101,8 @@ extern "C" {
  *
  * Subsequent calls will not call the given routine.
  *
+ * @param routine
+ *   The callback.
  * @param once
  *   The once variable designating that the given routine will be called only once.
  *
diff --git a/level_1/fl_control_group/c/control_group.h b/level_1/fl_control_group/c/control_group.h
index 2b343b2..e541a8c 100644
--- a/level_1/fl_control_group/c/control_group.h
+++ b/level_1/fl_control_group/c/control_group.h
@@ -41,7 +41,7 @@ extern "C" {
 /**
  * Apply the given control groups to the process represented by the PID.
  *
- * @param control
+ * @param control_group
  *   The control group(s) to apply.
  * @param id
  *   The PID of the process to apply the control group(s) to.
diff --git a/level_1/fl_print/c/print.h b/level_1/fl_print/c/print.h
index b3c519a..8fa7284 100644
--- a/level_1/fl_print/c/print.h
+++ b/level_1/fl_print/c/print.h
@@ -1443,8 +1443,6 @@ extern "C" {
  *
  * @param buffer
  *   The string to output.
- * @param offset
- *   The inclusive start point to start printing.
  * @param except_at
  *   An array of locations within the given string to not print.
  *   The array of locations is required/assumed to be in linear order.
diff --git a/level_1/fl_string/c/string.h b/level_1/fl_string/c/string.h
index f1e0f59..ed2a882 100644
--- a/level_1/fl_string/c/string.h
+++ b/level_1/fl_string/c/string.h
@@ -713,6 +713,8 @@ extern "C" {
  *   String to compare.
  * @param string2
  *   String to compare.
+ * @param range1
+ *   A range within the string1 to restrict the comparison to.
  * @param range2
  *   A range within the string2 to restrict the comparison to.
  *
diff --git a/level_1/fl_utf_file/c/utf_file.h b/level_1/fl_utf_file/c/utf_file.h
index 7ab342a..60e0cd4 100644
--- a/level_1/fl_utf_file/c/utf_file.h
+++ b/level_1/fl_utf_file/c/utf_file.h
@@ -237,8 +237,8 @@ extern "C" {
  * @param file
  *   The file to write to.
  *   The file must already be open.
- * @param destination
- *   The destination to write to the file.
+ * @param buffer
+ *   The string to write to the file.
  * @param range
  *   An inclusive start an stop range within the destination to read.
  * @param written
diff --git a/level_2/fll_control_group/c/control_group.h b/level_2/fll_control_group/c/control_group.h
index b72f1e6..760566e 100644
--- a/level_2/fll_control_group/c/control_group.h
+++ b/level_2/fll_control_group/c/control_group.h
@@ -36,7 +36,7 @@ extern "C" {
  *
  * This does not, however, create the control_group.path and will error out if that directory does not exist.
  *
- * @param control
+ * @param control_group
  *   The control group(s) to ensure the directories exist.
  *
  * @return
diff --git a/level_2/fll_print/c/print.h b/level_2/fll_print/c/print.h
index 78199e1..f083132 100644
--- a/level_2/fll_print/c/print.h
+++ b/level_2/fll_print/c/print.h
@@ -1115,8 +1115,6 @@ extern "C" {
  *
  * @param string
  *   The string to output.
- * @param length
- *   The total number of characters to print.
  * @param output
  *   The file stream to output to, including standard streams such as stdout and stderr.
  *
-- 
1.8.3.1