From: Arran Cudbard-Bell Date: Sun, 30 Dec 2012 23:34:06 +0000 (+0000) Subject: Update doxygen documentation X-Git-Tag: release_3_0_0_beta1~1335^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=45607c9c0eba9059114aa93ead0f216193be28e2;p=thirdparty%2Ffreeradius-server.git Update doxygen documentation --- diff --git a/doc/source/extra/toc.c b/doc/source/extra/toc.c index 3b9a0f2f31a..57a6bc30928 100644 --- a/doc/source/extra/toc.c +++ b/doc/source/extra/toc.c @@ -30,17 +30,17 @@ of modules in each stage. @code git://git.freeradius.org/freeradius-server.git @endcode -- Web: http://github.com/alandekok/freeradius-server/tree/master +- Web: http://github.com/FreeRADIUS/freeradius-server/tree/master -@subsection tree_21x 2.1.x stable tree +@subsection tree_2xx 2.x.x stable tree @code git clone git://git.freeradius.org/freeradius-server.git cd freeradius-server -git fetch origin v2.1.x:v2.1.x -git checkout v2.1.x +git fetch origin v2.x.x:v2.x.x +git checkout v2.x.x @endcode -- Web: http://github.com/alandekok/freeradius-server/tree/v2.1.x +- Web: http://github.com/FreeRADIUS/freeradius-server/tree/v2.x.x @section main_website Website @@ -60,11 +60,10 @@ freeradius-users@lists.freeradius.org @subsection dev_list FreeRADIUS-devel -This list is for development of the server, including patches, new -features and blah blah. PLEASE DO NOT post questions related to the -operation of the server here - use the "users" list. All of the -developers read both, and will answer your questions there if they -have the time. +This list is for development of the server, including patches, and +new features. PLEASE DO NOT post questions related to the operation +of the server here - use the "users" list. Most of the developers +read both, and will answer your questions there if they have the time. @code freeradius-devel@lists.freeradius.org diff --git a/src/lib/valuepair.c b/src/lib/valuepair.c index 43e588b997f..2fc8ecd36af 100644 --- a/src/lib/valuepair.c +++ b/src/lib/valuepair.c @@ -258,7 +258,7 @@ VALUE_PAIR * pairfind(VALUE_PAIR *first, unsigned int attr, unsigned int vendor, * * Delete matching pairs from the attribute list. * - * @param[in+out] first VP in list. + * @param[in,out] first VP in list. * @param[in] attr to match. * @param[in] vendor to match. * @param[in] tag to match. TAG_ANY matches any tag, TAG_UNUSED matches tagless VPs. @@ -311,7 +311,7 @@ void pairadd(VALUE_PAIR **first, VALUE_PAIR *add) * * @note Memory used by the VP being replaced will be freed. * - * @param[in+out] first VP in linked list. Will search and replace in this list. + * @param[in,out] first VP in linked list. Will search and replace in this list. * @param[in] replace VP to replace. * @return a copy of the input vp */ @@ -473,8 +473,8 @@ VALUE_PAIR *paircopy(VALUE_PAIR *vp) * * @note Does not respect tags when matching. * - * @param[in+out] to destination list. - * @param[in+out] from source list. + * @param[in,out] to destination list. + * @param[in,out] from source list. * * @see radius_pairmove */ @@ -662,8 +662,8 @@ void pairmove(VALUE_PAIR **to, VALUE_PAIR **from) * @note pairfree should be called on the head of the old list to free unmoved attributes (if they're no longer needed). * - * @param[in+out] to destination list. - * @param[in+out] from source list. + * @param[in,out] to destination list. + * @param[in,out] from source list. * @param[in] attr to match, if PW_VENDOR_SPECIFIC and vendor 0, only VSAs will * be copied. * @param[in] vendor to match. diff --git a/src/main/valuepair.c b/src/main/valuepair.c index 0a3f8ff98da..f495866b7ce 100644 --- a/src/main/valuepair.c +++ b/src/main/valuepair.c @@ -944,7 +944,7 @@ VALUE_PAIR **radius_list(REQUEST *request, pair_lists_t list) * * @see dict_attrbyname * - * @param[in+out] name of attribute. + * @param[in,out] name of attribute. * @param[in] unknown the list to return if no qualifiers were found. * @return PAIR_LIST_UNKOWN if qualifiers couldn't be resolved to a list. */ @@ -988,7 +988,7 @@ pair_lists_t radius_list_name(const char **name, pair_lists_t unknown) * Resolve name to a current request. * * @see radius_list - * @param[in+out] request to use as context, and to write result to. + * @param[in,out] request to use as context, and to write result to. * @param[in] name (request) to resolve to. * @return 0 if request is valid in this context, else -1. */ @@ -1031,6 +1031,7 @@ int radius_request(REQUEST **request, request_refs_t name) * * @see radius_list_name * @param[in,out] name of attribute. + * @param[in] unknown Request ref to return if no request qualifier is present. * @return one of the REQUEST_* definitions or REQUEST_UNKOWN */ request_refs_t radius_request_name(const char **name, request_refs_t unknown) @@ -1055,7 +1056,7 @@ request_refs_t radius_request_name(const char **name, request_refs_t unknown) /** Release memory allocated to value pair template. * - * @param[in+out] tmpl to free. + * @param[in,out] tmpl to free. */ void radius_tmplfree(VALUE_PAIR_TMPL **tmpl) { @@ -1163,8 +1164,7 @@ VALUE_PAIR_TMPL *radius_attr2tmpl(const char *name, /** Convert module specific attribute id to VALUE_PAIR_TMPL. * * @param[in] name string to convert. - * @param[out] vpt to modify. - * @return 0 + * @return pointer to new VPT. */ VALUE_PAIR_TMPL *radius_str2tmpl(const char *name) { @@ -1205,8 +1205,9 @@ void radius_mapfree(VALUE_PAIR_MAP **map) /** Convert CONFIG_PAIR to VALUE_PAIR_MAP. * - * Treats the left operand as a .. reference - * and the right operand as a module specific value. + * Treats the left operand as a + * @verbatim..@endverbatim reference and the right + * operand as a module specific value. * * The left operand will be pre-parsed into request ref, dst list, and da, * the right operand will be left as a string. diff --git a/src/main/xlat.c b/src/main/xlat.c index d733b654e62..c0638505ceb 100644 --- a/src/main/xlat.c +++ b/src/main/xlat.c @@ -72,8 +72,8 @@ static const char * const xlat_foreach_names[] = {"Foreach-Variable-0", #endif static int xlat_inst[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8 }; /* up to 8 for regex */ -/** - * @brief Convert the value on a VALUE_PAIR to string +/** Convert the value on a VALUE_PAIR to string + * */ static int valuepair2str(char * out,int outlen,VALUE_PAIR * pair, int type) { @@ -468,8 +468,8 @@ static size_t xlat_packet(void *instance, REQUEST *request, return valuepair2str(out, outlen, vp, da->type); } -/** - * @brief Print data as integer, not as VALUE. +/** Print data as integer, not as VALUE. + * */ static size_t xlat_integer(UNUSED void *instance, REQUEST *request, const char *fmt, char *out, size_t outlen) @@ -512,8 +512,8 @@ static size_t xlat_integer(UNUSED void *instance, REQUEST *request, return 0; } -/** - * @brief Print data as hex, not as VALUE. +/** Print data as hex, not as VALUE. + * */ static size_t xlat_hex(UNUSED void *instance, REQUEST *request, const char *fmt, char *out, size_t outlen) @@ -549,8 +549,8 @@ static size_t xlat_hex(UNUSED void *instance, REQUEST *request, return len * 2; } -/** - * @brief Print data as base64, not as VALUE +/** Print data as base64, not as VALUE + * */ static size_t xlat_base64(UNUSED void *instance, REQUEST *request, const char *fmt, char *out, size_t outlen) @@ -591,8 +591,8 @@ static size_t xlat_base64(UNUSED void *instance, REQUEST *request, return enc; } -/** - * @brief Prints the current module processing the request +/** Prints the current module processing the request + * */ static size_t xlat_module(UNUSED void *instance, REQUEST *request, UNUSED const char *fmt, char *out, size_t outlen) @@ -603,8 +603,7 @@ static size_t xlat_module(UNUSED void *instance, REQUEST *request, } #ifdef WITH_UNLANG -/** - * @brief Implements the Foreach-Variable-X +/** Implements the Foreach-Variable-X * * @see modcall() */ @@ -627,8 +626,7 @@ static size_t xlat_foreach(void *instance, REQUEST *request, } #endif -/** - * @brief Print data as string, if possible. +/** Print data as string, if possible. * * If attribute "Foo" is defined as "octets" it will normally * be printed as 0x0a0a0a. The xlat "%{string:Foo}" will instead @@ -660,8 +658,8 @@ static size_t xlat_string(UNUSED void *instance, REQUEST *request, return len; } -/** - * @brief xlat expand string attribute value +/** xlat expand string attribute value + * */ static size_t xlat_xlat(UNUSED void *instance, REQUEST *request, const char *fmt, char *out, size_t outlen) @@ -684,8 +682,8 @@ static size_t xlat_xlat(UNUSED void *instance, REQUEST *request, } #ifdef HAVE_REGEX_H -/* - * @brief Expand regexp matches %{0} to %{8} +/** Expand regexp matches %{0} to %{8} + * */ static size_t xlat_regex(void *instance, REQUEST *request, const char *fmt, char *out, size_t outlen) @@ -711,8 +709,7 @@ static size_t xlat_regex(void *instance, REQUEST *request, } #endif /* HAVE_REGEX_H */ -/** - * @brief Dynamically change the debugging level for the current request +/** Dynamically change the debugging level for the current request * * Example %{debug:3} */ @@ -776,8 +773,7 @@ static xlat_t *xlat_find(const char *module) } -/** - * @brief Register an xlat function. +/** Register an xlat function. * * @param module xlat name * @param func xlat function to be called @@ -906,15 +902,14 @@ int xlat_register(const char *module, RAD_XLAT_FUNC func, void *instance) return 0; } -/** - * @brief Unregister an xlat function. +/** Unregister an xlat function * - * We can only have one function to call per name, so the - * passing of "func" here is extraneous. + * We can only have one function to call per name, so the passing of "func" + * here is extraneous. * - * @param module xlat to unregister - * @param func Unused - * @return Void. + * @param [in] module xlat to unregister. + * @param [in] func + * @param [in] instance */ void xlat_unregister(const char *module, RAD_XLAT_FUNC func, void *instance) { @@ -936,8 +931,8 @@ void xlat_unregister(const char *module, RAD_XLAT_FUNC func, void *instance) rbtree_deletebydata(xlat_root, c); } -/** - * @brief De-register all xlat functions, used mainly for debugging. +/** De-register all xlat functions, used mainly for debugging. + * */ void xlat_free(void) { @@ -945,22 +940,22 @@ void xlat_free(void) } -/** - * @brief Decode an attribute name into a string. +/** Decode an attribute name into a string * * This expands the various formats: * - %{Name} * - %{xlat:name} * - %{Name:-Other} * - * calls radius_xlat() to do most of the work + * Calls radius_xlat() to do most of the work. * - * @param from string to expand - * @param to buffer for output - * @param freespace space remaining in output buffer - * @param request current server request - * @param func optional function to escape output; passed to radius_xlat() - * @return 0 on success, -1 on failure + * @param [in] from string to expand. + * @param [in,out] to buffer for output. + * @param [in] freespace remaining in output buffer. + * @param [in] request Current server request. + * @param [in] func Optional function to escape output; passed to radius_xlat(). + * @param [in] funcarg pointer to pass to escape function. + * @return 0 on success, -1 on failure. */ static int decode_attribute(const char **from, char **to, int freespace, REQUEST *request, @@ -1208,21 +1203,21 @@ done: return 0; } -/** - * @brief Replace %whatever in a string. +/** Replace %whatever in a string. * - * See 'doc/variables.txt' for more information. + * See 'doc/variables.txt' for more information. * - * @param out output buffer - * @param outlen size of output buffer - * @param fmt string to expand - * @param request current request - * @param func function to escape final value e.g. SQL quoting + * @param [out] out output buffer. + * @param [in] outlen size of output buffer. + * @param [in] fmt string to expand. + * @param [in] request current request. + * @param [in] func function to escape final value e.g. SQL quoting. + * @param [in] funcarg pointer to pass to escape function. * @return length of string written @bug should really have -1 for failure */ size_t radius_xlat(char *out, int outlen, const char *fmt, - REQUEST *request, - RADIUS_ESCAPE_STRING func, void *funcarg) + REQUEST *request, + RADIUS_ESCAPE_STRING func, void *funcarg) { int c, len, freespace; const char *p; diff --git a/src/modules/rlm_rest/rest.c b/src/modules/rlm_rest/rest.c index 0a0ac8d0a01..744886a95ce 100644 --- a/src/modules/rlm_rest/rest.c +++ b/src/modules/rlm_rest/rest.c @@ -848,7 +848,7 @@ static ssize_t rest_read_wrapper(char **buffer, rest_read_t func, * @see rest_read_ctx_free * * @param[in] request Current request. - * @param[in] read to initialise. + * @param[in] ctx to initialise. * @param[in] sort If TRUE VALUE_PAIRs will be sorted within the VALUE_PAIR * pointer array. */ @@ -916,7 +916,7 @@ static void rest_read_ctx_init(REQUEST *request, * * @see rest_read_ctx_init * - * @param[in] read to free. + * @param[in] ctx to free. */ static void rest_read_ctx_free(rlm_rest_read_t *ctx) { @@ -931,6 +931,7 @@ static void rest_read_ctx_free(rlm_rest_read_t *ctx) * for example 64bit integers converted to 32bit integers. Warn the user * when this happens. * + * @param[in] request Current request. * @param[in] raw string from decoder. * @param[in] vp containing parsed value. */ @@ -1490,7 +1491,6 @@ static VALUE_PAIR *json_pairmake(rlm_rest_t *instance, * * @param[in] instance configuration data. * @param[in] section configuration data. - * @param[in] g to use. * @param[in] request Current request. * @param[in] raw buffer containing JSON data. * @param[in] rawlen Length of data in raw buffer. @@ -1811,7 +1811,7 @@ static void rest_write_ctx_init(REQUEST *request, rlm_rest_write_t *ctx, /** Frees the intermediary buffer created by rest_write. * - * @param[in] data to be freed. + * @param[in] ctx data to be freed. */ static void rest_write_free(rlm_rest_write_t *ctx) { @@ -2351,6 +2351,7 @@ void rest_request_cleanup(UNUSED rlm_rest_t *instance, * @param[out] out Where to write escaped string. * @param[in] outlen Size of out buffer. * @param[in] raw string to be urlencoded. + * @param[in] arg pointer, gives context for escaping. * @return length of data written to out (excluding NULL). */ static size_t rest_uri_escape(UNUSED REQUEST *request, char *out, size_t outlen,