From 38d7ca08710400a0cfe4400b5699211c063c1b3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=96zg=C3=BCr=20Kesim?= Date: Thu, 7 Jul 2022 11:59:06 +0200 Subject: -fixed doxygen errors --- src/include/taler_extensions.h | 87 ++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 32 deletions(-) (limited to 'src/include/taler_extensions.h') diff --git a/src/include/taler_extensions.h b/src/include/taler_extensions.h index 342faad2a..8e1823cce 100644 --- a/src/include/taler_extensions.h +++ b/src/include/taler_extensions.h @@ -35,7 +35,8 @@ enum TALER_Extension_Type }; /* - * Represents the implementation of an extension. + * @brief Represents the implementation of an extension. + * * TODO: add documentation */ struct TALER_Extension @@ -50,20 +51,20 @@ struct TALER_Extension void *config; json_t *config_json; - void (*disable)(struct TALER_Extension *this); + void (*disable)(struct TALER_Extension *ext); enum GNUNET_GenericReturnValue (*test_json_config)( const json_t *config); enum GNUNET_GenericReturnValue (*load_json_config)( - struct TALER_Extension *this, + struct TALER_Extension *ext, json_t *config); json_t *(*config_to_json)( - const struct TALER_Extension *this); + const struct TALER_Extension *ext); enum GNUNET_GenericReturnValue (*load_taler_config)( - struct TALER_Extension *this, + struct TALER_Extension *ext, const struct GNUNET_CONFIGURATION_Handle *cfg); }; @@ -72,7 +73,8 @@ struct TALER_Extension */ /* - * Sets the configuration of the extensions from the given TALER configuration + * @brief Sets the configuration of the extensions from the given TALER + * configuration. * * @param cfg Handle to the TALER configuration * @return GNUNET_OK on success, GNUNET_SYSERR if unknown extensions were found @@ -83,8 +85,14 @@ TALER_extensions_load_taler_config ( const struct GNUNET_CONFIGURATION_Handle *cfg); /* - * Check the given obj to be a valid extension object and fill the fields - * accordingly. + * @brief Checks the given obj to be a valid extension object and fill the + * fields accordingly. + * + * @param[in] obj Object to verify is a valid extension + * @param{out] critical will be set to 1 if the extension is critical according to obj + * @param[out] version will be set to the version of the extension according to obj + * @param[out] config will be set to the configuration of the extension according to obj + * @return OK on success, Error otherwise */ enum GNUNET_GenericReturnValue TALER_extensions_is_json_config ( @@ -94,27 +102,27 @@ TALER_extensions_is_json_config ( json_t **config); /* - * Sets the configuration of the extensions from a given JSON object. + * @brief Sets the configuration of the extensions from a given JSON object. * - * he JSON object must be of type ExchangeKeysResponse as described in + * The JSON object must be of type ExchangeKeysResponse as described in * https://docs.taler.net/design-documents/006-extensions.html#exchange * * @param cfg JSON object containing the configuration for all extensions - * @return #GNUNET_OK on success, #GNUNET_SYSERR if unknown extensions were found - * or any particular configuration couldn't be parsed. + * @return #GNUNET_OK on success, #GNUNET_SYSERR if unknown extensions were + * found or any particular configuration couldn't be parsed. */ enum GNUNET_GenericReturnValue TALER_extensions_load_json_config ( json_t *cfg); /* - * Returns the head of the linked list of extensions + * @brief Returns the head of the linked list of extensions. */ const struct TALER_Extension * TALER_extensions_get_head (); /* - * Adds an extension to the linked list of extensions + * @brief Adds an extension to the linked list of extensions. * * @param new_extension the new extension to be added * @return GNUNET_OK on success, GNUNET_SYSERR if the extension is invalid @@ -126,7 +134,7 @@ TALER_extensions_add ( struct TALER_Extension *new_extension); /** - * Finds and returns a supported extension by a given type. + * @brief Finds and returns a supported extension by a given type. * * @param type type of the extension to lookup * @return extension found, or NULL (should not happen!) @@ -137,7 +145,7 @@ TALER_extensions_get_by_type ( /** - * Finds and returns a supported extension by a given name. + * @brief Finds and returns a supported extension by a given name. * * @param name name of the extension to lookup * @return the extension, if found, NULL otherwise @@ -149,7 +157,7 @@ TALER_extensions_get_by_name ( #define TALER_extensions_is_enabled(ext) (NULL != (ext)->config) /** - * Check if a given type of an extension is enabled + * @brief Check if a given type of an extension is enabled * * @param type type of to check * @return true enabled, false if not enabled, will assert if type is not found. @@ -207,13 +215,28 @@ TALER_extension_age_restriction_register (); * * The string must consist of a colon-separated list of increasing integers * between 0 and 31. Each entry represents the beginning of a new age group. - * F.e. the string "8:10:12:14:16:18:21" parses into the following list of age - * groups - * 0-7, 8-9, 10-11, 12-13, 14-15, 16-17, 18-20, 21-... - * which then is represented as bit mask with the corresponding bits set: - * 31 24 16 8 0 - * | | | | | - * oooooooo oo1oo1o1 o1o1o1o1 ooooooo1 + * F.e. the string + * + * "8:10:12:14:16:18:21" + * + * represents the following list of eight age groups: + * + * | Group | Ages | + * | -----:|:------------- | + * | 0 | 0, 1, ..., 7 | + * | 1 | 8, 9 | + * | 2 | 10, 11 | + * | 3 | 12, 13 | + * | 4 | 14, 15 | + * | 5 | 16, 17 | + * | 6 | 18, 19, 20 | + * | 7 | 21, ... | + * + * which is then encoded as a bit mask with the corresponding bits set: + * + * 31 24 16 8 0 + * | | | | | + * oooooooo oo1oo1o1 o1o1o1o1 ooooooo1 * * @param groups String representation of age groups * @param[out] mask Mask representation for age restriction. @@ -225,7 +248,7 @@ TALER_parse_age_group_string ( struct TALER_AgeMask *mask); /** - * Encodes the age mask into a string, like "8:10:12:14:16:18:21" + * @brief Encodes the age mask into a string, like "8:10:12:14:16:18:21" * * @param mask Age mask * @return String representation of the age mask, allocated by GNUNET_malloc. @@ -236,35 +259,35 @@ TALER_age_mask_to_string ( const struct TALER_AgeMask *mask); /** - * Returns true when age restriction is configured and enabled. + * @brief Returns true when age restriction is configured and enabled. */ bool TALER_extensions_age_restriction_is_enabled (); /** - * Returns true when age restriction is configured (might not be _enabled_, - * though). + * @brief Returns true when age restriction is configured (might not be + * _enabled_, though). */ bool TALER_extensions_age_restriction_is_configured (); /** - * Returns the currently set age mask. Note that even if age restriction is - * not enabled, the age mask might be have a non-zero value. + * @brief Returns the currently set age mask. Note that even if age + * restriction is not enabled, the age mask might be have a non-zero value. */ struct TALER_AgeMask TALER_extensions_age_restriction_ageMask (); /** - * Returns the amount of age groups defined. 0 means no age restriction + * @brief Returns the amount of age groups defined. 0 means no age restriction * enabled. */ size_t TALER_extensions_age_restriction_num_groups (); /** - * Parses a JSON object { "age_groups": "a:b:...y:z" }. + * @brief Parses a JSON object { "age_groups": "a:b:...y:z" }. * * @param root is the json object * @param[out] mask on success, will contain the age mask -- cgit v1.2.3