Settings documentation

include/fluidsynth/settings.h

@@ -26,8 +26,9 @@ extern "C" {
 #endif
 
 /**
- * @defgroup Settings Settings
- * @brief Functions for settings management
+ * @defgroup settings Settings
+ *
+ * Functions for settings management
  *
  * To create a synthesizer object you will have to specify its
  * settings. These settings are stored in a fluid_settings_t object.
@@ -154,6 +155,7 @@ int fluid_settings_getint_range(fluid_settings_t *settings, const char *name,
 
 /**
  * Callback function type used with fluid_settings_foreach_option()
+ *
  * @param data User defined data pointer
  * @param name Setting name
  * @param option A string option for this setting (iterates through the list)
@@ -172,6 +174,7 @@ FLUIDSYNTH_API char *fluid_settings_option_concat(fluid_settings_t *settings,
 
 /**
  * Callback function type used with fluid_settings_foreach()
+ *
  * @param data User defined data pointer
  * @param name Setting name
  * @param type Setting type (#fluid_types_enum)
@@ -181,7 +184,6 @@ typedef void (*fluid_settings_foreach_t)(void *data, const char *name, int type)
 FLUIDSYNTH_API
 void fluid_settings_foreach(fluid_settings_t *settings, void *data,
                             fluid_settings_foreach_t func);
-
 /* @} */
 
 #ifdef __cplusplus

src/utils/fluid_settings.c

@@ -255,6 +255,7 @@ delete_fluid_set_setting(fluid_setting_node_t *node)
 
 /**
  * Create a new settings object
+ *
  * @return the pointer to the settings object
  */
 fluid_settings_t *
@@ -278,6 +279,7 @@ new_fluid_settings(void)
 
 /**
  * Delete the provided settings object
+ *
  * @param settings a settings object
  */
 void
@@ -1015,15 +1017,17 @@ error_recovery:
 
 /**
  * Copy the value of a string setting into the provided buffer (thread safe)
+ *
  * @param settings a settings object
  * @param name a setting's name
  * @param str Caller supplied buffer to copy string value to
  * @param len Size of 'str' buffer (no more than len bytes will be written, which
  *   will always include a zero terminator)
  * @return #FLUID_OK if the value exists, #FLUID_FAILED otherwise
- * @since 1.1.0
  *
  * @note A size of 256 should be more than sufficient for the string buffer.
+ *
+ * @since 1.1.0
  */
 int
 fluid_settings_copystr(fluid_settings_t *settings, const char *name,
@@ -1075,14 +1079,16 @@ fluid_settings_copystr(fluid_settings_t *settings, const char *name,
 
 /**
  * Duplicate the value of a string setting
+ *
  * @param settings a settings object
  * @param name a setting's name
  * @param str Location to store pointer to allocated duplicate string
  * @return #FLUID_OK if the value exists and was successfully duplicated, #FLUID_FAILED otherwise
- * @since 1.1.0
  *
  * Like fluid_settings_copystr() but allocates a new copy of the string.  Caller
  * owns the string and should free it with fluid_free() when done using it.
+ *
+ * @since 1.1.0
  */
 int
 fluid_settings_dupstr(fluid_settings_t *settings, const char *name, char **str)
@@ -1194,13 +1200,14 @@ fluid_settings_str_equal(fluid_settings_t *settings, const char *name, const cha
 }
 
 /**
- * Get the default value of a string setting.  Note that the returned string is
- * not owned by the caller and should not be modified or freed.
+ * Get the default value of a string setting.
  *
  * @param settings a settings object
  * @param name a setting's name
  * @param def the default string value of the setting if it exists
  * @return FLUID_OK on success, FLUID_FAILED otherwise
+ *
+ * @note The returned string is* not owned by the caller and should not be modified or freed.
  */
 int
 fluid_settings_getstr_default(fluid_settings_t *settings, const char *name, char **def)
@@ -1240,6 +1247,7 @@ fluid_settings_getstr_default(fluid_settings_t *settings, const char *name, char
 
 /**
  * Add an option to a string setting (like an enumeration value).
+ *
  * @param settings a settings object
  * @param name a setting's name
  * @param s option string to add
@@ -1277,6 +1285,7 @@ fluid_settings_add_option(fluid_settings_t *settings, const char *name, const ch
 
 /**
  * Remove an option previously assigned by fluid_settings_add_option().
+ *
  * @param settings a settings object
  * @param name a setting's name
  * @param s option string to remove
@@ -1602,6 +1611,7 @@ fluid_settings_getint(fluid_settings_t *settings, const char *name, int *val)
 
 /**
  * Get the range of values of an integer setting
+ *
  * @param settings a settings object
  * @param name a setting's name
  * @param min setting's range lower limit
@@ -1727,10 +1737,12 @@ fluid_settings_foreach_option(fluid_settings_t *settings, const char *name,
 
 /**
  * Count option string values for a string setting.
+ *
  * @param settings a settings object
  * @param name Name of setting
  * @return Count of options for this string setting (0 if none, -1 if not found
  *   or not a string setting)
+ *
  * @since 1.1.0
  */
 int
@@ -1758,11 +1770,13 @@ fluid_settings_option_count(fluid_settings_t *settings, const char *name)
 
 /**
  * Concatenate options for a string setting together with a separator between.
+ *
  * @param settings Settings object
  * @param name Settings name
  * @param separator String to use between options (NULL to use ", ")
  * @return Newly allocated string or NULL on error (out of memory, not a valid
  *   setting \p name or not a string setting). Free the string when finished with it by using fluid_free().
+ *
  * @since 1.1.0
  */
 char *