-fixed doxygen errors

4 files changed, 67 insertions, 56 deletions

diff --git a/src/exchange/taler-exchange-httpd_management_extensions.c b/src/exchange/taler-exchange-httpd_management_extensions.c
index 83a1dfc97..a663b1b06 100644
--- a/src/exchange/taler-exchange-httpd_management_extensions.c
+++ b/src/exchange/taler-exchange-httpd_management_extensions.c
@@ -180,7 +180,7 @@ verify_extensions_from_json (
       return GNUNET_SYSERR;
 
     if (critical != extension->critical
-        || 0 != strcmp (version, extension->version) // TODO: libtool compare?
+        || 0 != strcmp (version, extension->version) // FIXME-oec: libtool compare
         || NULL == config
         || GNUNET_OK != extension->test_json_config (config))
       return GNUNET_SYSERR;
diff --git a/src/extensions/extension_age_restriction.c b/src/extensions/extension_age_restriction.c
index fedf12d44..8cc30f57b 100644
--- a/src/extensions/extension_age_restriction.c
+++ b/src/extensions/extension_age_restriction.c
@@ -37,14 +37,6 @@ struct age_restriction_config
  */
 static struct age_restriction_config TE_age_restriction_config = {0};
 
-/**
- * @param groups String representation of the age groups. Must be of the form
- *  a:b:...:n:m
- * with
- *  0 < a < b <...< n < m < 32
- * @param[out] mask Bit representation of the age groups.
- * @return Error if string was invalid, OK otherwise.
- */
 enum GNUNET_GenericReturnValue
 TALER_parse_age_group_string (
   const char *groups,
@@ -89,13 +81,6 @@ TALER_parse_age_group_string (
 }
 
 
-/**
- * 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.
- *         Can be used as value in the TALER config.
- */
 char *
 TALER_age_mask_to_string (
   const struct TALER_AgeMask *m)
@@ -143,6 +128,8 @@ TALER_age_mask_to_string (
 
 /**
  * @brief implements the TALER_Extension.disable interface.
+ *
+ * @param ext Pointer to the current extension
  */
 void
 age_restriction_disable (
@@ -166,9 +153,9 @@ age_restriction_disable (
 
 /**
  * @brief implements the TALER_Extension.load_taler_config interface.
+ *
+ * @param ext Pointer to the current extension
  * @param cfg Handle to the GNUNET configuration
- * @param[out] enabled Set to true if age restriction is enabled in the config, false otherwise.
- * @param[out] mask Mask for age restriction. Will be 0 if age restriction was not enabled in the config.
  * @return Error if extension for age restriction was set, but age groups were
  *         invalid, OK otherwise.
  */
@@ -244,8 +231,9 @@ age_restriction_load_taler_config (
 
 /**
  * @brief implements the TALER_Extension.load_json_config interface.
+ *
  * @param ext if NULL, only tests the configuration
- * @param config the configuration as json
+ * @param jconfig the configuration as json
  */
 static enum GNUNET_GenericReturnValue
 age_restriction_load_json_config (
@@ -295,8 +283,9 @@ age_restriction_load_json_config (
 
 /**
  * @brief implements the TALER_Extension.load_json_config interface.
+ *
  * @param ext if NULL, only tests the configuration
- * @param config the configuration as json
+ * @return configuration as json_t* object
  */
 json_t *
 age_restriction_config_to_json (
@@ -328,6 +317,9 @@ age_restriction_config_to_json (
 
 /**
  * @brief implements the TALER_Extension.test_json_config interface.
+ *
+ * @param config configuration as json_t* to test
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise.
  */
 static enum GNUNET_GenericReturnValue
 age_restriction_test_json_config (
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
diff --git a/src/util/tv_age_restriction.c b/src/util/tv_age_restriction.c
index a2b0a7451..2958c14a8 100644
--- a/src/util/tv_age_restriction.c
+++ b/src/util/tv_age_restriction.c
@@ -34,10 +34,6 @@ get_age_group (
 
 /**
  * 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.
- *         Can be used as value in the TALER config.
  */
 char *
 age_mask_to_string (