Added some Doxygen documentation.

diff --git a/src/ngircd/ngircd.c b/src/ngircd/ngircd.c
index 31f08eeede2e60c80bc366619baab2745ccd4866..33dfdbc55600465ab9a9314e506cc05cc8250c3f 100644 (file)
--- a/src/ngircd/ngircd.c
+++ b/src/ngircd/ngircd.c
@@ -7,14 +7,18 @@
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version.
  * Please read the file COPYING, README and AUTHORS for more information.
- *
- * Main program -- main()
  */
 
 
 #include "portab.h"
 
-static char UNUSED id[] = "$Id: ngircd.c,v 1.95 2005/03/19 18:43:49 fw Exp $";
+static char UNUSED id[] = "$Id: ngircd.c,v 1.96 2005/06/01 21:52:18 alex Exp $";
+
+/**
+ * @file
+ * The main program, including the C function main() which is called
+ * by the loader of the operating system.
+ */
 
 #include "imp.h"
 #include <assert.h>
@@ -66,6 +70,14 @@ LOCAL void Fill_Version PARAMS(( void ));
 LOCAL void Setup_FDStreams PARAMS(( void ));
 
 
+/**
+ * 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.
+ */
 GLOBAL int
 main( int argc, const char *argv[] )
 {
@@ -391,6 +403,12 @@ main( int argc, const char *argv[] )
 } /* main */
 
 
+/**
+ * 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.
+ */
 LOCAL void
 Fill_Version( void )
 {
@@ -447,6 +465,9 @@ Fill_Version( void )
 } /* Fill_Version */
 
 
+/**
+ * Reload the server configuration file.
+ */
 GLOBAL void
 NGIRCd_Rehash( void )
 {
@@ -484,6 +505,9 @@ NGIRCd_Rehash( void )
 } /* NGIRCd_Rehash */
 
 
+/**
+ * Initialize the signal handler.
+ */
 LOCAL void
 Initialize_Signal_Handler( void )
 {
@@ -531,13 +555,15 @@ Initialize_Signal_Handler( void )
 } /* Initialize_Signal_Handler */
 
 
+/**
+ * Signal handler of ngIRCd.
+ * This function is called whenever ngIRCd catches a signal sent by the
+ * user and/or the system to it. For example SIGTERM and SIGHUP.
+ * @param Signal Number of the signal to handle.
+ */
 LOCAL void
 Signal_Handler( int Signal )
 {
-       /* Signal-Handler. Dieser wird aufgerufen, wenn eines der Signale eintrifft,
-        * fuer das wir uns registriert haben (vgl. Initialize_Signal_Handler). Die
-        * Nummer des eingetroffenen Signals wird der Funktion uebergeben. */
-
        switch( Signal )
        {
                case SIGTERM:
@@ -563,6 +589,9 @@ Signal_Handler( int Signal )
 } /* Signal_Handler */
 
 
+/**
+ * Display copyright and version information of ngIRCd on the console.
+ */
 LOCAL void
 Show_Version( void )
 {
@@ -574,6 +603,11 @@ Show_Version( void )
 } /* Show_Version */
 
 
+/**
+ * Display a short help text on the console.
+ * This help depends on the configuration of the executable and only shows
+ * options that are actually enabled.
+ */
 LOCAL void
 Show_Help( void )
 {
@@ -592,6 +626,9 @@ Show_Help( void )
 } /* Show_Help */
 
 
+/**
+ * Delete the file containing the process ID (PID).
+ */
 LOCAL void
 Pidfile_Delete( void )
 {
@@ -607,6 +644,10 @@ Pidfile_Delete( void )
 } /* Pidfile_Delete */
 
 
+/**
+ * Create the file containing the process ID of ngIRCd ("PID file").
+ * @param pid The process ID to be stored in this file.
+ */
 LOCAL void
 Pidfile_Create( long pid )
 {
@@ -635,6 +676,9 @@ Pidfile_Create( long pid )
 } /* Pidfile_Create */
 
 
+/**
+ * Redirect stdin, stdout and stderr to apropriate file handles.
+ */
 LOCAL void
 Setup_FDStreams( void )
 {

diff --git a/src/ngircd/parse.c b/src/ngircd/parse.c
index de6e696056830120a53539b11fa3e2999078b6bb..e36b3e7e14b2cc1c3ad4e4a97bf77d13175a5cb4 100644 (file)
--- a/src/ngircd/parse.c
+++ b/src/ngircd/parse.c
@@ -7,14 +7,17 @@
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version.
  * Please read the file COPYING, README and AUTHORS for more information.
- *
- * IRC command parser and validator
  */
 
 
 #include "portab.h"
 
-static char UNUSED id[] = "$Id: parse.c,v 1.61 2005/03/19 18:43:49 fw Exp $";
+static char UNUSED id[] = "$Id: parse.c,v 1.62 2005/06/01 21:52:18 alex Exp $";
+
+/**
+ * @file
+ * IRC command parser and validator.
+ */
 
 #include "imp.h"
 #include <assert.h>
@@ -109,6 +112,12 @@ LOCAL bool Validate_Args PARAMS(( CONN_ID Idx, REQUEST *Req, bool *Closed ));
 LOCAL bool Handle_Request PARAMS(( CONN_ID Idx, REQUEST *Req ));
 
 
+/**
+ * Return the pointer to the global "IRC command structure".
+ * This structure, an array of type "COMMAND" describes all the IRC commands
+ * implemented by ngIRCd and how to handle them.
+ * @return Pointer to the global command structure.
+ */
 GLOBAL COMMAND *
 Parse_GetCommandStruct( void )
 {
@@ -116,13 +125,27 @@ Parse_GetCommandStruct( void )
 } /* Parse_GetCommandStruct */
 
 
+/**
+ * Parse a command ("request") received from a client.
+ * 
+ * This function is called after the connection layer received a valid CR+LF
+ * terminated line of text: we asume that this is a valid IRC command and
+ * try to do something useful with it :-)
+ *
+ * All errors are reported to the client from which the command has been
+ * received, and if the error is fatal this connection is closed down.
+ *
+ * This function is able to parse the syntax as described in RFC 2812,
+ * section 2.3.
+ *
+ * @param Idx Index of the connection from which the command has been received.
+ * @param Request NULL terminated line of text (the "command").
+ * @return true on success (valid command or "regular" error), false if a
+ *     fatal error occured and the connection has been shut down.
+ */
 GLOBAL bool
 Parse_Request( CONN_ID Idx, char *Request )
 {
-       /* Client-Request parsen. Bei einem schwerwiegenden Fehler wird
-        * die Verbindung geschlossen und false geliefert.
-        * Der Aufbau gueltiger Requests ist in RFC 2812, 2.3 definiert. */
-
        REQUEST req;
        char *start, *ptr;
        bool closed;
@@ -220,6 +243,10 @@ Parse_Request( CONN_ID Idx, char *Request )
 } /* Parse_Request */
 
 
+/**
+ * Initialize request structure.
+ * @param Req Request structure to be initialized.
+ */
 LOCAL void
 Init_Request( REQUEST *Req )
 {