fix various doxygen warnings

include/fluidsynth/sfont.h

@@ -133,7 +133,7 @@ typedef int (* fluid_sfloader_callback_read_t )(void *buf, int count, void * han
 typedef int (* fluid_sfloader_callback_seek_t )(void * handle, long offset, int origin);
 
 /** 
- * Closes the handle returned by #fluid_sfloader_callback_open and frees used ressources.
+ * Closes the handle returned by #fluid_sfloader_callback_open_t and frees used ressources.
  * 
  * @return returns #FLUID_OK on success, #FLUID_FAILED on error
  */

include/fluidsynth/synth.h

@@ -291,6 +291,9 @@ FLUIDSYNTH_API void fluid_synth_get_voicelist(fluid_synth_t* synth,
                                               fluid_voice_t* buf[], int bufsize, int ID);
 FLUIDSYNTH_API int fluid_synth_handle_midi_event(void* data, fluid_midi_event_t* event);
 
+/**
+ * Specifies the type of filter to use for the custom IIR filter
+ */
 enum fluid_iir_filter_type {
     FLUID_IIR_DISABLED = 0, /**< Custom IIR filter is not operating */
     FLUID_IIR_LOWPASS, /**< Custom IIR filter is operating as low-pass filter */
@@ -298,6 +301,9 @@ enum fluid_iir_filter_type {
     FLUID_IIR_LAST /**< @internal Value defines the count of filter types (#fluid_iir_filter_type) @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */
 };
 
+/**
+ * Specifies optional settings to use for the custom IIR filter
+ */
 enum fluid_iir_filter_flags {
     FLUID_IIR_Q_LINEAR = 1 << 0, /**< The Soundfont spec requires the filter Q to be interpreted in dB. If this flag is set the filter Q is instead assumed to be in a linear range */
     FLUID_IIR_Q_ZERO_OFF = 1 << 1, /**< If this flag the filter is switched off if Q == 0 (prior to any transformation) */

src/bindings/fluid_filerenderer.c

@@ -283,6 +283,7 @@ new_fluid_file_renderer(fluid_synth_t* synth)
 /**
  * Set vbr encoding quality (only available with libsndfile support)
  * @param dev File renderer object.
+ * @param q The encoding quality, see libsndfile documentation of \c SFC_SET_VBR_ENCODING_QUALITY
  * @return #FLUID_OK if the quality has been successfully set, #FLUID_FAILED otherwise
  * @since 1.1.7
  */

src/sfloader/fluid_sfont.c

@@ -336,7 +336,7 @@ int fluid_preset_set_data(fluid_preset_t* preset, void* data)
 /**
  * Retrieve the private data of a SoundFont preset instance.
  * 
- * @param sfont The SoundFont preset instance.
+ * @param preset The SoundFont preset instance.
  * @return The private data or NULL if none explicitly set before.
  */
 void* fluid_preset_get_data(fluid_preset_t* preset)
@@ -402,6 +402,8 @@ delete_fluid_sample(fluid_sample_t* sample)
  * Returns the size of the fluid_sample_t structure.
  * 
  * Useful in low latency scenarios e.g. to allocate a sample on the stack.
+ * 
+ * @return Size of fluid_sample_t in bytes
  */
 size_t fluid_sample_sizeof()
 {
@@ -520,6 +522,7 @@ error_rec:
 /**
  * Set the loop of a sample.
  * 
+ * @param sample SoundFont sample
  * @param loop_start Start sample index of the loop.
  * @param loop_end End index of the loop (must be a valid sample as it marks the last sample to be played).
  * @return #FLUID_OK on success, #FLUID_FAILED otherwise.
@@ -537,7 +540,8 @@ int fluid_sample_set_loop(fluid_sample_t* sample, unsigned int loop_start, unsig
 /**
  * Set the pitch of a sample.
  * 
- * @param rootkey Root MIDI note of sample (0-127)
+ * @param sample SoundFont sample
+ * @param root_key Root MIDI note of sample (0-127)
  * @param fine_tune Fine tune in cents
  * @return #FLUID_OK on success, #FLUID_FAILED otherwise.
  */

src/synth/fluid_mod.c

@@ -41,7 +41,7 @@ fluid_mod_clone(fluid_mod_t* mod, const fluid_mod_t* src)
 
 /**
  * Set a modulator's primary source controller and flags.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @param src Modulator source (#fluid_mod_src or a MIDI controller number)
  * @param flags Flags determining mapping function and whether the source
  *   controller is a general controller (#FLUID_MOD_GC) or a MIDI CC controller
@@ -56,7 +56,7 @@ fluid_mod_set_source1(fluid_mod_t* mod, int src, int flags)
 
 /**
  * Set a modulator's secondary source controller and flags.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @param src Modulator source (#fluid_mod_src or a MIDI controller number)
  * @param flags Flags determining mapping function and whether the source
  *   controller is a general controller (#FLUID_MOD_GC) or a MIDI CC controller
@@ -71,7 +71,7 @@ fluid_mod_set_source2(fluid_mod_t* mod, int src, int flags)
 
 /**
  * Set the destination effect of a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @param dest Destination generator (#fluid_gen_type)
  */
 void
@@ -82,7 +82,7 @@ fluid_mod_set_dest(fluid_mod_t* mod, int dest)
 
 /**
  * Set the scale amount of a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @param amount Scale amount to assign
  */
 void
@@ -93,7 +93,7 @@ fluid_mod_set_amount(fluid_mod_t* mod, double amount)
 
 /**
  * Get the primary source value from a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @return The primary source value (#fluid_mod_src or a MIDI CC controller value).
  */
 int
@@ -104,7 +104,7 @@ fluid_mod_get_source1(const fluid_mod_t* mod)
 
 /**
  * Get primary source flags from a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @return The primary source flags (#fluid_mod_flags).
  */
 int
@@ -115,7 +115,7 @@ fluid_mod_get_flags1(const fluid_mod_t* mod)
 
 /**
  * Get the secondary source value from a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @return The secondary source value (#fluid_mod_src or a MIDI CC controller value).
  */
 int
@@ -126,7 +126,7 @@ fluid_mod_get_source2(const fluid_mod_t* mod)
 
 /**
  * Get secondary source flags from a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @return The secondary source flags (#fluid_mod_flags).
  */
 int
@@ -137,7 +137,7 @@ fluid_mod_get_flags2(const fluid_mod_t* mod)
 
 /**
  * Get destination effect from a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @return Destination generator (#fluid_gen_type)
  */
 int
@@ -148,7 +148,7 @@ fluid_mod_get_dest(const fluid_mod_t* mod)
 
 /**
  * Get the scale amount from a modulator.
- * @param mod Modulator
+ * @param mod The modulator instance
  * @return Scale amount
  */
 double
@@ -446,6 +446,8 @@ delete_fluid_mod (fluid_mod_t *mod)
  * Returns the size of the fluid_mod_t structure.
  * 
  * Useful in low latency scenarios e.g. to allocate a modulator on the stack.
+ * 
+ * @return Size of fluid_mod_t in bytes
  */
 size_t fluid_mod_sizeof()
 {
@@ -473,6 +475,7 @@ fluid_mod_test_identity (const fluid_mod_t *mod1, const fluid_mod_t *mod2)
 /**
  * Check if the modulator has the given source.
  * 
+ * @param mod The modulator instance
  * @param cc Boolean value indicating if ctrl is a CC controller or not
  * @param ctrl The source to check for (if \c cc == FALSE : a value of type #fluid_mod_src, else the value of the MIDI CC to check for)
  * 
@@ -496,6 +499,7 @@ int fluid_mod_has_source(const fluid_mod_t * mod, int cc, int ctrl)
 
 /**
  * Check if the modulator has the given destination.
+ * @param mod The modulator instance
  * @param gen The destination generator of type #fluid_gen_type to check for
  * @return TRUE if the modulator has the given destination, FALSE otherwise.
  */

src/synth/fluid_synth.c

@@ -5075,8 +5075,18 @@ fluid_synth_get_settings(fluid_synth_t* synth)
 }
 
 /**
- * Same as calling \c fluid_synth_set_gen2(synth, chan, param, value, FALSE, FALSE)
+ * Set a SoundFont generator (effect) value on a MIDI channel in real-time.
+ * @param synth FluidSynth instance
+ * @param chan MIDI channel number (0 to MIDI channel count - 1)
+ * @param param SoundFont generator ID (#fluid_gen_type)
+ * @param value Offset or absolute generator value to assign to the MIDI channel
  * @return #FLUID_OK on success, #FLUID_FAILED otherwise
+ *
+ * This function allows for setting all effect parameters in real time on a
+ * MIDI channel. Setting absolute to non-zero will cause the value to override
+ * any generator values set in the instruments played on the MIDI channel.
+ * See SoundFont 2.01 spec, paragraph 8.1.3, page 48 for details on SoundFont
+ * generator parameters and valid ranges.
  */
 int fluid_synth_set_gen(fluid_synth_t* synth, int chan, int param, float value)
 {
@@ -5277,6 +5287,7 @@ fluid_synth_stop_LOCAL (fluid_synth_t *synth, unsigned int id)
  * @param synth FluidSynth instance
  * @param sfont_id ID of a loaded SoundFont
  * @param offset Bank offset value to apply to all instruments
+ * @return #FLUID_OK if the offset was set successfully, #FLUID_FAILED otherwise
  */
 int
 fluid_synth_set_bank_offset(fluid_synth_t* synth, int sfont_id, int offset)