Fixed and cleaned up Doxygen comments

2 files changed, 87 insertions, 10 deletions

diff --git a/utils/benchmark.c b/utils/benchmark.c
index 6b01fb7..77cd759 100644
--- a/utils/benchmark.c
+++ b/utils/benchmark.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   benchmark.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-03-22
+ *
+ * @brief  Benchmarking utility to test how quickly a computer can calculate SHA512 hashes
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -28,16 +38,30 @@
 #include <eurephia_nullsafe.h>
 #include <eurephia_context.h>
 
-#define ROUNDS_MIN 1000
-#define ROUNDS_MAX 999999999
+#define ROUNDS_MIN 1000         /**< Define minimum acceptable rounds for the hashing */
+#define ROUNDS_MAX 999999999    /**< Define maximum allowed rounds for the hashing */
 
-// Internal functions found in passwd.c
+/**
+ * @copydoc pack_saltinf()
+ */
 int pack_saltinfo(char *buf, int buflen, int rounds, int saltlen, const char *pwd);
+
+/**
+ * @copydoc sha512_crypt_r()
+ */
 inline char *sha512_crypt_r(const char *key, const char *salt, size_t maxrounds_cfg, char *buffer, int buflen);
+
+/**
+ * @copydoc gen_randsaltstr()
+ */
 int gen_randsaltstr(eurephiaCTX *ctx, char *saltstr, int len);
 
-// A function which calculates a hash based on a standard password, used
-// for measuring the time used for hash calculation
+/**
+ * Internal function which calculates a hash based on a standard password.  This function is used
+ * for measuring the time used for hash calculation
+ *
+ * @param rounds  Number of rounds the hashing should use
+ */
 void benchmark_hashing(int rounds) {
         char *buffer = NULL;
         char *pwdhash = NULL;
@@ -72,6 +96,15 @@ void benchmark_hashing(int rounds) {
 }
 
 
+/**
+ * Internal function, calculating a time delta between two struct timeval.
+ *
+ * @param result Result pointer to where the result will be put
+ * @param x      Value 1 with time information
+ * @param y      Value 2 with time information
+ *
+ * @return Returns 1 if the X value is lower than the Y value
+ */
 int timeval_subtract (result, x, y)
      struct timeval *result, *x, *y;
 {
@@ -96,6 +129,14 @@ int timeval_subtract (result, x, y)
         return x->tv_sec < y->tv_sec;
 }
 
+
+/**
+ * Internal function.  The real benchmark function.
+ *
+ * @param rounds Number of rounds to do when hashing a password
+ *
+ * @return Returns a struct timeval containing the time spent calculating the hash
+ */
 struct timeval *do_benchmark(int rounds) {
         struct timeval start, end, *timediff = NULL;
 
@@ -110,10 +151,20 @@ struct timeval *do_benchmark(int rounds) {
         return timediff;
 }
 
-// This function will try to find the best minium and maximum rounds for
-// the SHA512 hashing.  The values are returned in the min and max variables
-// and the thr_min and thr_max defines the minimum and maximum thresholds in
-// milliseconds the hashing algorithm should use.
+/**
+ * This function will try to find the best minium and maximum rounds for
+ * the SHA512 hashing.  The values are returned in the min and max variables
+ * and the thr_min and thr_max defines the minimum and maximum thresholds in
+ * milliseconds the hashing algorithm should use.
+ *
+ * @param min      Return pointer for the minimum hashing rounds value
+ * @param max      Return pointer for the maximum hashing rounds value
+ * @param thr_min  Allow the calculation of hashes to last for thr_min ms.
+ * @param thr_max  Do not allow the hash calculation to exceed thr_max ms.
+ *
+ * @return Returns 1 if a good suggestion for min and max hashing rounds was found.
+ *         Otherwise 0 is returned.
+ */
 int benchmark(int *min, int *max, int thr_min, int thr_max) {
         int i = 0, success = 0;
         struct timeval *time = NULL, min_time, max_time ;
diff --git a/utils/eurephia_init.c b/utils/eurephia_init.c
index 7b72eb5..e0f998d 100644
--- a/utils/eurephia_init.c
+++ b/utils/eurephia_init.c
@@ -49,13 +49,24 @@
 #include <eurephia_values.h>
 #include <eurephia_xml.h>
 
-#define MODULE "eurephia_init"
+#define MODULE "eurephia_init"  /**< Set the module name to eurephia_init */
 #include <client_context.h>
 #include <argparser.h>
 #include <get_console_input.h>
 
+/**
+ * @copydoc benchmark()
+ */
 int benchmark(int *min, int *max, int thr_min, int thr_max);
 
+
+/**
+ * Prints program version information to stdout
+ *
+ * @param fprg String containing full path to this binary (argv[0])
+ *
+ * @return Returns the basename value of the binary
+ */
 char *print_version(char *fprg) {
         char *prg = basename(fprg);
 
@@ -65,6 +76,12 @@ char *print_version(char *fprg) {
         return prg;
 }
 
+
+/**
+ * Prints a help screen for all arguments eurephia_init can process
+ *
+ * @param fprg String containing full path to this binary (argv[0])
+ */
 void print_help(char *fprg) {
         print_version(fprg);
 
@@ -530,6 +547,15 @@ int setup_iptables(eurephiaCTX *ctx) {
 }
 #endif
 
+
+/**
+ * Main function of eurephia_init
+ *
+ * @param argc
+ * @param argv
+ *
+ * @return Returns 0 on success, otherwise a positive integer on failure.
+ */
 int main(int argc, char **argv) {
         // Default hash calculation thresholds for benchmarking
         int hash_thr_min = 95;   // 95ms