From 998eeee471871ce07bc80255d84b16e8e7df5922 Mon Sep 17 00:00:00 2001
From: derselbst <tom.mbrt@googlemail.com>
Date: Fri, 22 Jan 2021 19:46:03 +0100
Subject: [PATCH] Elaborate API docs of fluid_audio_func_t

---
 include/fluidsynth/audio.h | 27 +++++++++++++++++++++++++++
 src/synth/fluid_synth.c    |  2 +-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/include/fluidsynth/audio.h b/include/fluidsynth/audio.h
index 4eca1788..6c0e9357 100644
--- a/include/fluidsynth/audio.h
+++ b/include/fluidsynth/audio.h
@@ -70,12 +70,39 @@ extern "C" {
  * This function is responsible for rendering audio to the buffers.
  * The buffers passed to this function are allocated and owned by the respective
  * audio driver and are only valid during that specific call (do not cache them).
+ * The buffers have already been zeroed-out.
  * For further details please refer to fluid_synth_process().
  *
+ * @parblock
  * @note Whereas fluid_synth_process() allows aliasing buffers, there is the guarentee that @p out
  * and @p fx buffers provided by fluidsynth's audio drivers never alias. This prevents downstream
  * applications from e.g. applying a custom effect accidentially to the same buffer multiple times.
+ * @endparblock
  *
+ * @parblock
+ * @note Also note that the Jack driver is currently the only driver that has dedicated @p fx buffers
+ * (but only if \setting{audio_jack_multi} is true). All other drivers do not provide @p fx buffers.
+ * In this case, users are encouraged to mix the effects into the provided dry buffers when calling
+ * fluid_synth_process().
+ * @code{.cpp}
+int myCallback(void *, int len, int nfx, float *fx[], int nout, float *out[])
+{
+    int ret;
+    if(nfx == 0)
+    {
+        float *fxb[4] = {out[0], out[1], out[0], out[1]};
+        ret = fluid_synth_process(synth, len, sizeof(fxb) / sizeof(fxb[0]), fxb, nout, out);
+    }
+    else
+    {
+        ret = fluid_synth_process(synth, len, nfx, fx, nout, out);
+    }
+    // ... client-code ...
+    return ret;
+}
+ * @endcode
+ * For other possible use-cases refer to \ref fluidsynth_process.c .
+ * @endparblock
  */
 typedef int (*fluid_audio_func_t)(void *data, int len,
                                   int nfx, float *fx[],
diff --git a/src/synth/fluid_synth.c b/src/synth/fluid_synth.c
index f0a4ab19..f5fe1225 100644
--- a/src/synth/fluid_synth.c
+++ b/src/synth/fluid_synth.c
@@ -3888,7 +3888,7 @@ static FLUID_INLINE void fluid_synth_mix_single_buffer(float *FLUID_RESTRICT out
  * @param len Count of audio frames to synthesize and store in every single buffer provided by \p out and \p fx.
  * Zero value is permitted, the function does nothing and return FLUID_OK.
  *
- * @param nfx Count of arrays in \c fx. Must be a multiple of 2 (because of stereo).
+ * @param nfx Count of arrays in \c fx. Must be a multiple of 2 (because of stereo)
  * and in the range <code>0 <= nfx/2 <= (fluid_synth_count_effects_channels() * fluid_synth_count_effects_groups())</code>.
  * Note that zero value is valid and allows to skip mixing effects in all fx output buffers.
  *