Move some doxygen comments into the source file

The doxygen documentation is best placed into the source file. It is easier
to spot any discrepancy.

diff --git a/documentation/usertab.txt b/documentation/usertab.txt
deleted file mode 100644 (file)
index a9c5653..0000000
--- a/documentation/usertab.txt
+++ /dev/null
@@ -1,115 +0,0 @@
-/*!\file
-\brief Provide a meanigfull name instead of the user ID or IP address shown in the
-reports.
-*/
-
-
-/*! \enum UserTabEnum
-The possible sources to map the user ID or IP address to the name to display
-in the reports.
-*/
-
-
-
-
-
-/*! \var enum UserTabEnum which_usertab
-Tell the database source to use to map the user ID or IP address to a meaningfull
-name.
-*/
-
-
-
-
-
-/*! \fn void init_usertab(const char *UserTabFile)
-Initialize the data used by user_find().
-
-If \a UserTabFile is ldap, the user ID is fetched from a LDAP server.
-
-\param UserTabFile The name of the file to read or ldap. If it is empty, the function does nothing.
-
-\note The memory and resources allocated by this function must be released by
-a call to close_usertab().
-*/
-
-
-
-
-
-/*! \fn void user_find(char *mappedname, int namelen, const char *userlogin)
-Find the real name of the user with the ID or IP address in \a userlogin. The name is fetched
-from the source initialized by init_usertab().
-
-The usertab data must have been initialized by init_usertab().
-
-\param mappedname A buffer to write the real name of the user.
-\param namelen The size of the buffer.
-\param userlogin The ID or IP address of the user.
-*/
-
-
-
-
-
-/*! \fn void close_usertab(void)
-Free the memory and resources allocated by init_usertab().
-*/
-
-
-
-
-
-/*! \fn static void init_file_usertab(const char *UserTabFile)
-Read the \a UserTabFile database.
-
-The file contains the IP address or ID of the user then some spaces and
-the real name of the user to show in the report.
-
-Any trailing space or tabulation is removed from the real name. The user ID or IP cannot contain
-a space or a tabulation but it may contain any other character, including the colon that was
-forbidden in the past. That change was made to allow IPv6 addresses.
-
-The file may contain comments if the line starts with a #.
-
-\param UserTabFile The name of the file to read.
-*/
-
-
-
-
-
-/*! \fn static void get_usertab_name(const char *user,char *name,int namelen)
-Get the real name of the user from the usertab file read by init_file_usertab().
-
-\param user The user ID or IP address to search.
-\param name The buffer to store the real name of the user.
-\param namelen The size of the \a name buffer.
-
-If the user ID or IP address isn't found, the output buffer \a name contains
-the unmatched input string.
-*/
-
-
-
-
-
-/*! \fn static void init_ldap_usertab(void)
-Initialize the communication with the LDAP server whose name is in
-::LDAPHost and connect to port ::LDAPPort.
-*/
-
-
-
-
-
-/*! \fn static void get_ldap_name(const char *userlogin,char *mappedname,int namelen)
-Get the real name of a user by searching the userlogin (user ID) in a LDAP.
-
-\param userlogin The user ID to search.
-\param name The buffer to store the real name of the user.
-\param namelen The size of the \a name buffer.
-
-If the user ID isn't found in the LDAP, the output buffer \a name contains
-the unmatched input string.
-*/

diff --git a/usertab.c b/usertab.c
index 639920c5b2caac22374462aa62b9fcff62141f70..454b8710b34819b06b23ec41ee406a6685d07fec 100644 (file)
--- a/usertab.c
+++ b/usertab.c
@@ -23,6 +23,10 @@
  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  *
  */
+/*!\file
+\brief Provide a meanigfull name instead of the user ID or IP address shown in the
+reports.
+*/
 
 #include "include/conf.h"
 #include "include/defs.h"
@@ -41,6 +45,10 @@
 
 #endif //HAVE_LDAP_H
 
+/*!
+The possible sources to map the user ID or IP address to the name to display
+in the reports.
+*/
 enum UserTabEnum
 {
        //! Users matched against the ::UserTabFile file.
@@ -51,6 +59,10 @@ enum UserTabEnum
        UTT_None
 };
 
+/*!
+Tell the database source to use to map the user ID or IP address to a meaningfull
+name.
+*/
 enum UserTabEnum which_usertab=UTT_None;
 
 static char *userfile=NULL;
@@ -68,6 +80,20 @@ static char *ldapconvbuffer=NULL;
 static int ldapconvbuffersize=0;
 #endif
 
+/*!
+Read the \a UserTabFile database.
+
+The file contains the IP address or ID of the user then some spaces and
+the real name of the user to show in the report.
+
+Any trailing space or tabulation is removed from the real name. The user ID or IP cannot contain
+a space or a tabulation but it may contain any other character, including the colon that was
+forbidden in the past. That change was made to allow IPv6 addresses.
+
+The file may contain comments if the line starts with a #.
+
+\param UserTabFile The name of the file to read.
+*/
 static void init_file_usertab(const char *UserTabFile)
 {
        FILE *fp_usr;
@@ -129,6 +155,16 @@ static void init_file_usertab(const char *UserTabFile)
        }
 }
 
+/*!
+Get the real name of the user from the usertab file read by init_file_usertab().
+
+\param user The user ID or IP address to search.
+\param name The buffer to store the real name of the user.
+\param namelen The size of the \a name buffer.
+
+If the user ID or IP address isn't found, the output buffer \a name contains
+the unmatched input string.
+*/
 static void get_usertab_name(const char *user,char *name,int namelen)
 {
        char warea[MAXLEN];
@@ -260,6 +296,16 @@ const char * charset_convert( const char * str_in, const char * charset_to )
 #endif //USE_ICONV
 }
 
+/*!
+Get the real name of a user by searching the userlogin (user ID) in a LDAP.
+
+\param userlogin The user ID to search.
+\param name The buffer to store the real name of the user.
+\param namelen The size of the \a name buffer.
+
+If the user ID isn't found in the LDAP, the output buffer \a name contains
+the unmatched input string.
+*/
 static void get_ldap_name(const char *userlogin,char *mappedname,int namelen)
 {
        /* Start searching username in cache */
@@ -341,6 +387,16 @@ static void get_ldap_name(const char *userlogin,char *mappedname,int namelen)
 }
 #endif //HAVE_LDAP_H
 
+/*!
+Initialize the data used by user_find().
+
+If \a UserTabFile is ldap, the user ID is fetched from a LDAP server.
+
+\param UserTabFile The name of the file to read or ldap. If it is empty, the function does nothing.
+
+\note The memory and resources allocated by this function must be released by
+a call to close_usertab().
+*/
 void init_usertab(const char *UserTabFile)
 {
        if (strcmp(UserTabFile, "ldap") == 0) {
@@ -365,6 +421,16 @@ void init_usertab(const char *UserTabFile)
        }
 }
 
+/*!
+Find the real name of the user with the ID or IP address in \a userlogin. The name is fetched
+from the source initialized by init_usertab().
+
+The usertab data must have been initialized by init_usertab().
+
+\param mappedname A buffer to write the real name of the user.
+\param namelen The size of the buffer.
+\param userlogin The ID or IP address of the user.
+*/
 void user_find(char *mappedname, int namelen, const char *userlogin)
 {
        if (which_usertab==UTT_File) {
@@ -380,6 +446,9 @@ void user_find(char *mappedname, int namelen, const char *userlogin)
        }
 }
 
+/*!
+Free the memory and resources allocated by init_usertab().
+*/
 void close_usertab(void)
 {
 #ifdef HAVE_LDAP_H