Added doxygen comments for the main eurephiadm parts

1 files changed, 100 insertions, 4 deletions

diff --git a/eurephiadm/eurephiadm.c b/eurephiadm/eurephiadm.c
index d07c46f..aceae91 100644
--- a/eurephiadm/eurephiadm.c
+++ b/eurephiadm/eurephiadm.c
@@ -19,6 +19,16 @@
  *
 */
 
+/**
+ * @file   eurephiadm.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-11-28
+ *
+ * @brief  Main part of the eurephiadm command line administration utility for eurephia
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -41,22 +51,47 @@
 #include "get_console_input.h"
 #include "commands.h"
 
+
+/**
+ * Prints version and copyright info to stdout
+ *
+ * @param fprg Full path to binary
+ *
+ * @return Returns the basename part of the binary file name
+ */
 char *print_version(char *fprg) {
         char *prg = basename(fprg);
 
         fprintf(stdout, "%s (v%s) - eurephia administration utility\n"
-                "Copyright (C) 2008  David Sommerseth <dazo@users.sourceforge.net>\n",
+                "Copyright (C) 2008, 2009  David Sommerseth <dazo@users.sourceforge.net>\n",
                 prg, EUREPHIAVERSION);
         return prg;
 }
 
 
+/**
+ * Wrapper function to be used by the command API in eurephiadm
+ *
+ */
 void help_Help() {
         char *argv[] = { MODULE, NULL };
 
         cmd_Help(NULL, NULL, NULL, 1, argv);
 }
 
+
+/**
+ * Displays a generic help screen, if no arguments where given, or else the
+ * the help screen for the eurephiadm command if it was found.
+ *
+ * @param ctx   eurephiaCTX
+ * @param sess  eurephiaSESSION of the current logged in user
+ * @param cfg   eurephiaVALUES struct of the current configuration
+ * @param argc  argument count for the eurephiadm command
+ * @param argv  argument table for the eurephiadm command
+ *
+ * @return returns 0 on success, otherwise 1.
+ */
 int cmd_Help(eurephiaCTX *ctx, eurephiaSESSION *sess, eurephiaVALUES *cfg, int argc, char **argv) {
         eurephiadm_functions *func = NULL;
         int i;
@@ -105,13 +140,38 @@ int cmd_Help(eurephiaCTX *ctx, eurephiaSESSION *sess, eurephiaVALUES *cfg, int a
         return 0;
 }
 
+
+/**
+ * eurephiadm logout command.  Logs out the current active session.
+ *
+ * @param ctx   eurephiaCTX
+ * @param sess  eurephiaSESSION of the current logged in user
+ * @param cfg   eurephiaVALUES struct of the current configuration
+ * @param argc  argument count for the logout command
+ * @param argv  argument table for the logout command
+ *
+ * @return returns 0 on success, otherwise 1.
+ */
 int cmd_Logout(eurephiaCTX *ctx, eurephiaSESSION *sess, eurephiaVALUES *cfg, int argc, char **argv) {
         int rc = 0;
         rc = eDBadminLogout(ctx, argv[0]);
-        fprintf(stdout, "%s\n", (rc == 1 ? "Logged out succesfully" : "Logout failed."));
+        fprintf(stdout, "%s\n", (rc == 1 ? "Logged out successfully" : "Logout failed."));
         return (rc == 0);
 }
 
+
+/**
+ * eurephiadm show-config command.  Dumps configuration to stdout.  If the user is logged in, the
+ * configuration saved in the database is also dumped.
+ *
+ * @param ctx   eurephiaCTX
+ * @param sess  eurephiaSESSION of the current logged in user
+ * @param cfg   eurephiaVALUES struct of the current configuration
+ * @param argc  argument count for the show-config command
+ * @param argv  argument table for the show-config command
+ *
+ * @return returns 0 on success, otherwise 1.
+ */
 int cmd_ShowCfg(eurephiaCTX *ctx, eurephiaSESSION *sess, eurephiaVALUES *cfg, int argc, char **argv) {
         void dump_values(eurephiaVALUES *vls) {
                 eurephiaVALUES *ptr = NULL;
@@ -138,6 +198,14 @@ int cmd_ShowCfg(eurephiaCTX *ctx, eurephiaSESSION *sess, eurephiaVALUES *cfg, in
 }
 
 
+/**
+ * Establish a connection to the database and register the database connection in the eurephiaCTX
+ *
+ * @param ctx    eurephiaCTX
+ * @param argstr argument string for the database connection
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eurephia_ConnectDB(eurephiaCTX *ctx, const char *argstr) {
         char *delims = " ";
         char *cp = NULL;
@@ -169,6 +237,17 @@ int eurephia_ConnectDB(eurephiaCTX *ctx, const char *argstr) {
         return 1;
 }
 
+
+/**
+ * Log in a user.  The function will ask for user name and password and authenticate the user against
+ * the eurephia database and make sure the user is granted access to the requested access level.
+ *
+ * @param ctx         eurephiaCTX
+ * @param cfg         eurephiaVALUES with configuration settings
+ * @param req_access  String (const char *) containing the requested access level.
+ *
+ * @return Returns a eurephiaSESSION pointer to the authenticated user session on success, otherwise NULL.
+ */
 eurephiaSESSION *do_login(eurephiaCTX *ctx, eurephiaVALUES *cfg, const char *req_access) {
         eurephiaSESSION *session = NULL;
         char username[33], password[33], *tmp = NULL;
@@ -211,6 +290,15 @@ eurephiaSESSION *do_login(eurephiaCTX *ctx, eurephiaVALUES *cfg, const char *req
         return session;
 }
 
+
+/**
+ * Converts a argument table (char **) into a space separated string (char *)
+ *
+ * @param argc argument counter
+ * @param argv argument array
+ *
+ * @return String (char *) of all arguments, separated by space.
+ */
 char *args2string(int argc, char **argv) {
         char *res = NULL;
         int len = 0, i = 0;
@@ -230,6 +318,14 @@ char *args2string(int argc, char **argv) {
 }
 
 
+/**
+ * eurephiadm main function
+ *
+ * @param argc argument counter
+ * @param argv argument table
+ *
+ * @return returns 0 on success, otherwise a value > 0
+ */
 int main(int argc, char **argv) {
         FILE *logfile = NULL;
         int loglevel = 0;
@@ -297,7 +393,7 @@ int main(int argc, char **argv) {
                 }
         }
 
-        // Find the command requested and save a pointer to that command's C function
+        // Find the command requested and save a pointer to that commands C function
         for( i = 0; cmdline_functions[i].command != NULL; i++ ) {
                 call_fnc = (eurephiadm_functions *)&cmdline_functions[i];
 
@@ -330,7 +426,7 @@ int main(int argc, char **argv) {
 
         //
         //  Load database driver, setup a context and create or reuse an open session
-        //  and then call the command's function
+        //  and then call the commando's function
         //
 
         // Create a eurephia context and load database driver