From: Frederic Marchal Date: Fri, 2 Oct 2015 17:25:10 +0000 (+0200) Subject: Move some doxygen comments into the source file X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=9049db377705b1d37ad4b49661f6200cad5e4cb0;p=thirdparty%2Fsarg.git 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 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 639920c..454b871 100644 --- 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