Alexander Barton : Doxygen'ify and update comments in ngircd.{c|h} - ngIRCd GIT Updates

13 Feb 2011

Module: ngircd.git
Branch: master
Commit: f3ec90f3f0e3e3b3ccfddda209ac94ba5ad92e42
URL:    http://ngircd.barton.de/cgi-bin/gitweb.cgi?p=ngircd.git&a=commit;h=f3ec9...
Author: Alexander Barton alex@barton.de
Date:   Mon Dec 27 17:31:19 2010 +0100
Doxygen'ify and update comments in ngircd.{c|h}
---
src/ngircd/ngircd.c |   54 ++++++++++++++++++++++++++++++++++-----------------
 src/ngircd/ngircd.h |   41 +++++++++++++++++++++++++++++---------
 2 files changed, 67 insertions(+), 28 deletions(-)

diff --git a/src/ngircd/ngircd.c b/src/ngircd/ngircd.c
index e595caf..4b49ec6 100644
--- a/src/ngircd/ngircd.c
+++ b/src/ngircd/ngircd.c
@@ -67,11 +67,13 @@ static bool NGIRCd_Init PARAMS(( bool ));
/**
  * The main() function of ngIRCd.
+ *
  * Here all starts: this function is called by the operating system loader,
  * it is the first portion of code executed of ngIRCd.
- * @param argc The number of arguments passed to ngIRCd on the command line.
- * @param argv An array containing all the arguments passed to ngIRCd.
- * @return Global exit code of ngIRCd, zero on success.
+ *
+ * @param argc	The number of arguments passed to ngIRCd on the command line.
+ * @param argv	An array containing all the arguments passed to ngIRCd.
+ * @return	Global exit code of ngIRCd, zero on success.
  */
 GLOBAL int
 main( int argc, const char *argv[] )
@@ -232,7 +234,7 @@ main( int argc, const char *argv[] )
    	}
    }
-	/* Debug-Level (for IRCs "VERSION" command) */
+	/* Debug level for "VERSION" command */
    NGIRCd_DebugLevel[0] = '\0';
 #ifdef DEBUG
    if( NGIRCd_Debug ) strcpy( NGIRCd_DebugLevel, "1" );
@@ -287,11 +289,9 @@ main( int argc, const char *argv[] )
    		exit(1);
    	}
-		/*
-		 * create protocol and server identification.
-		 * The syntax used by ngIRCd in PASS commands and the extended flags
-		 * are described in doc/Protocol.txt
-		 */
+		/* Create protocol and server identification. The syntax
+		 * used by ngIRCd in PASS commands and the known "extended
+		 * flags" are described in doc/Protocol.txt. */
 #ifdef IRCPLUS
    	snprintf( NGIRCd_ProtoID, sizeof NGIRCd_ProtoID, "%s%s %s|%s:%s", PROTOVER, PROTOIRCPLUS, PACKAGE_NAME, PACKAGE_VERSION, IRCPLUSFLAGS );
 #ifdef ZLIB
@@ -316,11 +316,10 @@ main( int argc, const char *argv[] )
    		Pidfile_Delete( );
    		exit( 1 );
    	}
-		
-		/* Hauptschleife */
+
+		/* Main Run Loop */
    	Conn_Handler( );
-		/* Alles abmelden */
    	Conn_Exit( );
    	Client_Exit( );
    	Channel_Exit( );
@@ -333,10 +332,12 @@ main( int argc, const char *argv[] )
/**
- * Generate ngIRCd "version string".
- * This string is generated once and then stored in NGIRCd_Version for
- * further usage, for example by the IRC command VERSION and the --version
- * command line switch.
+ * Generate ngIRCd "version strings".
+ *
+ * The ngIRCd version information is generated once and then stored in the
+ * NGIRCd_Version and NGIRCd_VersionAddition string variables for further
+ * usage, for example by the IRC command "VERSION" and the --version command
+ * line switch.
  */
 static void
 Fill_Version( void )
@@ -466,7 +467,8 @@ Pidfile_Delete( void )
/**
  * Create the file containing the process ID of ngIRCd ("PID file").
- * @param pid The process ID to be stored in this file.
+ *
+ * @param pid	The process ID to be stored in this file.
  */
 static void
 Pidfile_Create(pid_t pid)
@@ -504,6 +506,8 @@ Pidfile_Create(pid_t pid)
/**
  * Redirect stdin, stdout and stderr to apropriate file handles.
+ *
+ * @param fd	The file handle stdin, stdout and stderr should be redirected to.
  */
 static void
 Setup_FDStreams(int fd)
@@ -519,6 +523,13 @@ Setup_FDStreams(int fd)
 } /* Setup_FDStreams */
+/**
+ * Get user and group ID of unprivileged "nobody" user.
+ *
+ * @param uid	User ID
+ * @param gid	Group ID
+ * @return	true on success.
+ */
 static bool
 NGIRCd_getNobodyID(uid_t *uid, gid_t *gid )
 {
@@ -543,7 +554,7 @@ NGIRCd_getNobodyID(uid_t *uid, gid_t *gid )
    if ( !pwd->pw_uid || !pwd->pw_gid)
    	return false;
-	*uid = pwd->pw_uid;	
+	*uid = pwd->pw_uid;
    *gid = pwd->pw_gid;
    endpwent();
@@ -551,6 +562,13 @@ NGIRCd_getNobodyID(uid_t *uid, gid_t *gid )
 } /* NGIRCd_getNobodyID */
+/**
+ * Initialize ngIRCd daemon.
+ *
+ * @param NGIRCd_NoDaemon	Set to true if ngIRCd should run in the
+ *				foreground and not as a daemon.
+ * @return			true on success.
+ */
 static bool
 NGIRCd_Init( bool NGIRCd_NoDaemon ) 
 {
diff --git a/src/ngircd/ngircd.h b/src/ngircd/ngircd.h
index 143a9ff..2efb8a9 100644
--- a/src/ngircd/ngircd.h
+++ b/src/ngircd/ngircd.h
@@ -1,6 +1,6 @@
 /*
  * ngIRCd -- The Next Generation IRC Daemon
- * Copyright (c)2001,2002 by Alexander Barton (alex@barton.de)
+ * Copyright (c)2001-2010 Alexander Barton (alex@barton.de).
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -23,31 +23,52 @@
#define C_ARRAY_SIZE(x)	(sizeof(x)/sizeof((x)[0]))
+/** UNIX timestamp of ngIRCd start */
+GLOBAL time_t NGIRCd_Start;
-GLOBAL time_t NGIRCd_Start;		/* Startzeitpunkt des Daemon */
+/** ngIRCd start time as string, used for RPL_CREATED_MSG (003) */
 GLOBAL char NGIRCd_StartStr[64];
+
+/** ngIRCd version number containing release number and compile-time options */
 GLOBAL char NGIRCd_Version[126];
+
+/** String specifying the compile-time options and target platform */
 GLOBAL char NGIRCd_VersionAddition[126];
#ifdef DEBUG
-GLOBAL bool NGIRCd_Debug;		/* Debug-Modus aktivieren */
+/** Flag indicating if debug mode is active (true) or not (false) */
+GLOBAL bool NGIRCd_Debug;
 #endif
#ifdef SNIFFER
-GLOBAL bool NGIRCd_Sniffer;		/* Sniffer aktivieren */
+/** Flag indication if sniffer is active (true) or not (false) */
+GLOBAL bool NGIRCd_Sniffer;
 #endif
-GLOBAL bool NGIRCd_Passive;		/* nicht zu anderen Servern connecten */
+/**
+ * Flag indicating if NO outgoing connections should be established (true)
+ * or not (false, the default)
+ */
+GLOBAL bool NGIRCd_Passive;
-GLOBAL bool NGIRCd_SignalQuit;	/* true: quit server*/
-GLOBAL bool NGIRCd_SignalRestart;	/* true: restart server */
+/** Flag indicating that ngIRCd has been requested to quit (true) */
+GLOBAL bool NGIRCd_SignalQuit;
-GLOBAL char NGIRCd_DebugLevel[2];	/* Debug-Level fuer IRC_VERSION() */
+/** Flag indicating that ngIRCd has been requested to restart (true) */
+GLOBAL bool NGIRCd_SignalRestart;
-GLOBAL char NGIRCd_ConfFile[FNAME_LEN];	/* Konfigurationsdatei */
+/**
+ * Debug level for "VERSION" command, see description of numeric RPL_VERSION
+ * (351) in RFC 2812. ngIRCd sets debuglevel to 1 when the debug mode is
+ * active, and to 2 if the sniffer is running.
+ */
+GLOBAL char NGIRCd_DebugLevel[2];
-GLOBAL char NGIRCd_ProtoID[COMMAND_LEN];/* Protokoll- und Server-Identifikation */
+/** Full path and file name of current configuration file */
+GLOBAL char NGIRCd_ConfFile[FNAME_LEN];
+/** Protocol and server identification string; see doc/Protocol.txt */
+GLOBAL char NGIRCd_ProtoID[COMMAND_LEN];
#endif

    