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