Fix several doxygen warnings

.github/workflows/api_doc_build.yml

@@ -16,6 +16,7 @@ on:
 
 env:
   BUILD_TYPE: Release
+  DOXYGEN_VERSION: "1.17.0"
 
 concurrency:
     group: ${{ github.workflow }}-${{ github.ref }}
@@ -34,7 +35,14 @@ jobs:
       run: sudo apt-get update
 
     - name: Install Dependencies
-      run: sudo apt-get install doxygen xsltproc libxslt1-dev
+      run: sudo apt-get install xsltproc libxslt1-dev
+
+    - name: Install Doxygen ${{ env.DOXYGEN_VERSION }}
+      run: |
+        DOXYGEN_VERSION_UNDERSCORED="${DOXYGEN_VERSION//./_}"
+        curl --proto-redir =https -fsSL "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION_UNDERSCORED}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz" \
+          | sudo tar -xz --strip-components=1 -C /usr/local
+        doxygen --version
 
     - name: Create Build Environment
       run: cmake -E make_directory ${{runner.workspace}}/build

.gitignore

@@ -51,3 +51,8 @@ latex/
 /zensical_runtime.toml
 _codeql_build_dir/
 _codeql_detected_source_root
+
+# Auto-generated by CMake build targets -- not committed to version control
+doc/wiki/api/
+doc/wiki/settings/
+doc/wiki/usage/

Dockerfile

@@ -12,9 +12,9 @@ RUN zypper refresh && zypper install --no-recommends -y cmake pkg-config make gc
 
 RUN zypper refresh && zypper install --no-recommends -y clang
 
-RUN zypper refresh && zypper install --no-recommends -y doxygen astyle gdb sox find awk
+RUN zypper refresh && zypper install --no-recommends -y doxygen astyle gdb sox
 
-RUN zypper refresh && zypper install --no-recommends -y glib2-devel ninja
+RUN zypper refresh && zypper install --no-recommends -y glib2-devel ninja xsltproc
 
 # Documentation build dependencies:
 #   python3 + pipx     -- for zensical

doc/CMakeLists.txt

@@ -165,6 +165,10 @@ if ( DOXYGEN_FOUND )
   # a relative path.  The file is gitignored via the root .gitignore.
   if ( LIBXSLT_XSLTPROC_EXECUTABLE AND ZENSICAL_EXECUTABLE )
     set ( ZENSICAL_RUNTIME_CONFIG ${CMAKE_SOURCE_DIR}/zensical_runtime.toml )
+    if ( DOXYGEN_VERSION VERSION_LESS "1.15.0" )
+      message ( WARNING "Your doxygen version ${DOXYGEN_VERSION} is old. This logic has only been tested to work correctly with doxygen 1.15 and newer." )
+    endif ()
+
     add_custom_target ( zensical
         COMMAND ${CMAKE_COMMAND}
             -D WIKI_DIR=${WIKI_DOCS_DIR}

doc/Doxyfile.cmake

@@ -121,7 +121,6 @@ VERBATIM_HEADERS = NO
 # configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
 ALPHABETICAL_INDEX = YES
-COLS_IN_ALPHA_INDEX = 5
 IGNORE_PREFIX = 
 #---------------------------------------------------------------------------
 # configuration options related to the HTML output
@@ -167,7 +166,7 @@ LATEX_OUTPUT = latex
 LATEX_CMD_NAME = latex
 MAKEINDEX_CMD_NAME = makeindex
 COMPACT_LATEX = NO
-PAPER_TYPE = a4wide
+PAPER_TYPE = a4
 EXTRA_PACKAGES = 
 LATEX_HEADER = 
 PDF_HYPERLINKS = YES
@@ -228,15 +227,11 @@ TAGFILES =
 GENERATE_TAGFILE = 
 ALLEXTERNALS = NO
 EXTERNAL_GROUPS = YES
-PERL_PATH = /usr/bin/perl
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool   
 #---------------------------------------------------------------------------
-CLASS_DIAGRAMS = YES
-MSCGEN_PATH = 
 HIDE_UNDOC_RELATIONS = YES
 HAVE_DOT = NO
-DOT_FONTNAME =
 DOT_FONTPATH = 
 CLASS_GRAPH = YES
 COLLABORATION_GRAPH = YES
@@ -254,8 +249,6 @@ DOT_PATH =
 DOTFILE_DIRS = 
 DOT_GRAPH_MAX_NODES = 50
 MAX_DOT_GRAPH_DEPTH = 1000
-DOT_TRANSPARENT = YES
-DOT_MULTI_TARGETS = NO
 GENERATE_LEGEND = YES
 DOT_CLEANUP = YES
 #---------------------------------------------------------------------------

doc/wiki/BuildingForAndroid.md

@@ -51,7 +51,7 @@ to capture even more missing dependencies that the NDK requires and make sure th
 ## Getting started
 
 * Read the preface above!
-* [Seriously, read the preface](#Preface)!!
+* [Seriously, read the preface](#preface)!!
 * Download the Android NDK
 * Download [fluid-android-prepare.sh](https://gist.github.com/derselbst/885641b86b8bd0e5fd1b1d846d4b286b) and [fluid-android-compile.sh](https://gist.github.com/derselbst/88917bf177d25cfc1067a37b442dd5ff)
 * Open `fluid-android-prepare.sh` and study it

src/bindings/fluid_cmd.c

@@ -4114,7 +4114,11 @@ fluid_cmd_handler_destroy_hash_value(void *value)
 /**
  * Create a new command handler.
  *
- * See new_fluid_cmd_handler2() for more information.
+ * @sa See new_fluid_cmd_handler2() for more information.
+ *
+ * @param synth If not NULL, all the default synthesizer commands will be added to the new handler.
+ * @param router If not NULL, all the default midi_router commands will be added to the new handler.
+ * @return New command handler, or NULL if alloc failed
  */
 fluid_cmd_handler_t *new_fluid_cmd_handler(fluid_synth_t *synth, fluid_midi_router_t *router)
 {
@@ -4427,7 +4431,8 @@ void delete_fluid_client(fluid_client_t *client)
 /**
  * Create a new TCP/IP command shell server.
  *
- * See new_fluid_server2() for more information.
+ * @sa See new_fluid_server2() for more information.
+ * @return New shell server instance or NULL on error
  */
 fluid_server_t *
 new_fluid_server(fluid_settings_t *settings,

src/rvoice/fluid_chorus.c

@@ -626,7 +626,7 @@ static int new_mod_delay_line(fluid_chorus_t *chorus, int delay_length)
  * fluid_chorus_set() must be called at least one time after calling
  * new_fluid_chorus().
  *
- * @param sample_rate, audio sample rate in Hz.
+ * @param sample_rate audio sample rate in Hz.
  * @return pointer on chorus unit.
  */
 fluid_chorus_t *
@@ -706,7 +706,7 @@ fluid_chorus_reset(fluid_chorus_t *chorus)
  * Set one or more chorus parameters.
  *
  * @param chorus Chorus instance.
- * @param set Flags indicating which chorus parameters to set (#fluid_chorus_set_t).
+ * @param set Flags indicating which chorus parameters to set (fluid_chorus_set_t).
  * @param nr Chorus voice count (0-99, CPU time consumption proportional to
  *   this value).
  * @param level Chorus level (0.0-10.0).
@@ -927,9 +927,9 @@ fluid_chorus_samplerate_change(fluid_chorus_t *chorus, fluid_real_t sample_rate)
 /**
  * Process chorus by mixing the result in output buffer.
  * @param chorus pointer on chorus unit returned by new_fluid_chorus().
- * @param in, pointer on monophonic input buffer of FLUID_BUFSIZE samples.
- * @param left_out, right_out, pointers on stereo output buffers of
- *  FLUID_BUFSIZE samples.
+ * @param in pointer on monophonic input buffer of FLUID_BUFSIZE samples.
+ * @param left_out pointer on stereo output buffer (left channel) of FLUID_BUFSIZE samples.
+ * @param right_out pointer on stereo output buffer (right channel) of FLUID_BUFSIZE samples.
  */
 void fluid_chorus_processmix(fluid_chorus_t *chorus, const fluid_real_t *in,
                              fluid_real_t *left_out, fluid_real_t *right_out)
@@ -1002,9 +1002,9 @@ void fluid_chorus_processmix(fluid_chorus_t *chorus, const fluid_real_t *in,
 /**
  * Process chorus by putting the result in output buffer (no mixing).
  * @param chorus pointer on chorus unit returned by new_fluid_chorus().
- * @param in, pointer on monophonic input buffer of FLUID_BUFSIZE samples.
- * @param left_out, right_out, pointers on stereo output buffers of
- *  FLUID_BUFSIZE samples.
+ * @param in pointer on monophonic input buffer of FLUID_BUFSIZE samples.
+ * @param left_out pointer on stereo output buffer (left channel) of FLUID_BUFSIZE samples.
+ * @param right_out pointer on stereo output buffer (right channel) of FLUID_BUFSIZE samples.
  */
 /* Duplication of code ... (replaces sample data instead of mixing) */
 void fluid_chorus_processreplace(fluid_chorus_t *chorus, const fluid_real_t *in,

src/rvoice/fluid_rvoice.c

@@ -292,9 +292,9 @@ fluid_rvoice_check_sample_sanity(fluid_rvoice_t *voice)
  * Synthesize a voice to a buffer.
  *
  * @param voice rvoice to synthesize
- * @param dsp_buf Audio buffer to synthesize to (#FLUID_BUFSIZE in length)
+ * @param dsp_buf Audio buffer to synthesize to (FLUID_BUFSIZE in length)
  * @return Count of samples written to dsp_buf. (-1 means voice is currently
- * quiet, 0 .. #FLUID_BUFSIZE-1 means voice finished.)
+ * quiet, 0 .. FLUID_BUFSIZE-1 means voice finished.)
  *
  * Panning, reverb and chorus are processed separately. The dsp interpolation
  * routine is in (fluid_rvoice_dsp.c).
@@ -687,8 +687,7 @@ static FLUID_INLINE void fluid_rvoice_local_retrigger_attack(fluid_rvoice_t *voi
 /**
  * Used by legato Mode : multi_retrigger
  *  see fluid_synth_noteon_mono_legato_multi_retrigger()
- * @param voice the synthesis voice to be updated
-*/
+ */
 DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_multi_retrigger_attack)
 {
     fluid_rvoice_t *voice = obj;
@@ -743,15 +742,12 @@ DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_multi_retrigger_attack)
 
 /**
  * sets the portamento dsp parameters: dsp.pitchoffset, dsp.pitchinc
- * @param voice rvoice to set portamento.
- * @param countinc increment count number.
- * @param pitchoffset pitch offset to apply to voice dsp.pitch.
  *
  * Notes:
  * 1) To get continuous portamento between consecutive noteOn (n1,n2,n3...),
  *   pitchoffset is accumulated in current dsp pitchoffset.
  * 2) And to get constant portamento duration, dsp pitch increment is updated.
-*/
+ */
 DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_set_portamento)
 {
     fluid_rvoice_t *voice = obj;

src/rvoice/fluid_rvoice_mixer.c

@@ -823,6 +823,12 @@ DECLARE_FLUID_RVOICE_FUNCTION(fluid_rvoice_mixer_set_samplerate)
 /**
  * @param buf_count number of primary stereo buffers
  * @param fx_buf_count number of stereo effect buffers
+ * @param fx_units number of effects units
+ * @param sample_rate_max maximum sample rate
+ * @param sample_rate audio sample rate
+ * @param evthandler event handler for voice events
+ * @param extra_threads number of extra threads to use for rendering
+ * @param prio thread priority level
  */
 fluid_rvoice_mixer_t *
 new_fluid_rvoice_mixer(int buf_count, int fx_buf_count, int fx_units,
@@ -1032,7 +1038,7 @@ int fluid_rvoice_mixer_set_limiter(fluid_rvoice_mixer_t *mixer, fluid_real_t sam
  * @param fx_group index of the fx group to which parameters must be set.
  *  must be in the range [-1..mixer->fx_units[. If -1 the changes are applied to
  *  all fx units.
- * @param set Flags indicating which parameters should be set (#fluid_revmodel_set_t)
+ * @param set Flags indicating which parameters should be set (fluid_revmodel_set_t)
  * @param values table of parameters values.
  */
 void
@@ -1072,7 +1078,7 @@ fluid_rvoice_mixer_set_reverb_full(const fluid_rvoice_mixer_t *mixer,
  * @param mixer that contains all fx group units.
  * @param fx_group index of the fx group to get parameter from.
  *  must be in the range [0..mixer->fx_units[.
- * @param enum indicating the parameter to get.
+ * @param param indicating the parameter to get.
  *  FLUID_REVERB_ROOMSIZE, reverb room size value.
  *  FLUID_REVERB_DAMP, reverb damping value.
  *  FLUID_REVERB_WIDTH, reverb width value.
@@ -1096,7 +1102,7 @@ fluid_rvoice_mixer_reverb_get_param(const fluid_rvoice_mixer_t *mixer,
  *  must be in the range [-1..mixer->fx_units[. If -1 the changes are applied
  *  to all fx group.
  * Keep in mind, that the needed CPU time is proportional to 'nr'.
- * @param set Flags indicating which parameters to set (#fluid_chorus_set_t)
+ * @param set Flags indicating which parameters to set (fluid_chorus_set_t)
  * @param values table of pararameters.
  */
 void
@@ -1136,7 +1142,7 @@ fluid_rvoice_mixer_set_chorus_full(const fluid_rvoice_mixer_t *mixer,
  * @param mixer that contains all fx groups units.
  * @param fx_group index of the fx group to get parameter from.
  *  must be in the range [0..mixer->fx_units[.
- * @param get Flags indicating which parameter to get (#fluid_chorus_set_t)
+ * @param param Flags indicating which parameter to get
  * @return the parameter value (0.0 is returned if error)
  */
 double
@@ -1723,6 +1729,7 @@ static int fluid_rvoice_mixer_set_threads(fluid_rvoice_mixer_t *mixer, int threa
 
 /**
  * Synthesize audio into buffers
+ * @param mixer the mixer to render
  * @param blockcount number of blocks to render, each having FLUID_BUFSIZE samples
  * @return number of blocks rendered
  */

src/sfloader/fluid_defsfont.c

@@ -1299,8 +1299,8 @@ static int fluid_preset_zone_create_voice_zones(fluid_preset_zone_t *preset_zone
 /**
  * Checks if modulator mod is identical to another modulator in the list
  * (specs SF 2.0X  7.4, 7.8).
- * @param mod, modulator list.
- * @param name, if not NULL, pointer on a string displayed as warning.
+ * @param mod modulator list.
+ * @param name if not NULL, pointer on a string displayed as warning.
  * @return TRUE if mod is identical to another modulator, FALSE otherwise.
  */
 static int
@@ -1332,8 +1332,8 @@ fluid_zone_is_mod_identical(fluid_mod_t *mod, char *name)
  * This is appropriate to internal synthesizer modulators tables
  * which have a fixed size (FLUID_NUM_MOD).
  *
- * @param zone_name, zone name
- * @param list_mod, address of pointer on modulator list.
+ * @param zone_name zone name
+ * @param list_mod address of pointer on modulator list.
  */
 static void fluid_limit_mod_list(char *zone_name, fluid_mod_t **list_mod)
 {
@@ -1371,8 +1371,8 @@ static void fluid_limit_mod_list(char *zone_name, fluid_mod_t **list_mod)
  * Checks and remove invalid modulators from a zone modulators list.
  * - checks valid modulator sources (specs SF 2.01  7.4, 7.8, 8.2.1).
  * - checks identical modulators in the list (specs SF 2.01  7.4, 7.8).
- * @param zone_name, zone name.
- * @param list_mod, address of pointer on modulators list.
+ * @param zone_name zone name.
+ * @param list_mod address of pointer on modulators list.
  */
 static void
 fluid_zone_check_mod(char *zone_name, fluid_mod_t **list_mod)

src/synth/fluid_chan.c

@@ -442,7 +442,7 @@ fluid_channel_update_legato_staccato_state(fluid_channel_t *chan)
  * @param chan  fluid_channel_t.
  * @param key MIDI note number (0-127).
  * @param vel MIDI velocity (0-127, 0=noteoff).
- * @param onenote. When 1 the function adds the note but the monophonic list
+ * @param onenote When 1 the function adds the note but the monophonic list
  *                 keeps only one note (used on noteOn poly).
  * Note: i_last index keeps a trace of the most recent note added.
  *       prev_note keeps a trace of the note prior i_last note.
@@ -543,11 +543,9 @@ fluid_channel_search_monolist(fluid_channel_t *chan, unsigned char key, int *i_p
  * and relinked after the i_last element.
  *
  * @param chan  fluid_channel_t.
- * @param
- *   i, index of the note to remove. If i is invalid or the list is
+ * @param i index of the note to remove. If i is invalid or the list is
  *      empty, the function do nothing and returns FLUID_FAILED.
- * @param
- *   On input, i_prev is a pointer on index of the note previous i.
+ * @param i_prev pointer on index of the note previous i.
  *   On output i_prev is a pointer on index of the note previous i if i is the last note
  *   in the list,FLUID_FAILED otherwise. When the returned index is valid it means
  *   a legato detection on noteoff.
@@ -633,9 +631,9 @@ void fluid_channel_clear_monolist(fluid_channel_t *chan)
 /**
  * On noteOn on a polyphonic channel,adds the note into the monophonic list
  * keeping only this note.
- * @param
- *   chan  fluid_channel_t.
- *   key, vel, note and velocity added in the monolist
+ * @param chan  fluid_channel_t.
+ * @param key note number added in the monolist.
+ * @param vel velocity added in the monolist.
  * Note: i_last index keeps a trace of the most recent note inserted.
  *       prev_note keeps a trace of the note prior i_last note.
  *       FLUID_CHANNEL_LEGATO_PLAYING bit keeps trace of legato/staccato playing.
@@ -681,7 +679,7 @@ void fluid_channel_invalid_prev_note_staccato(fluid_channel_t *chan)
 /**
  * The function handles poly/mono commutation on legato pedal On/Off.
  * @param chan  fluid_channel_t.
- * @param value, value of the CC legato.
+ * @param value value of the CC legato.
  */
 void fluid_channel_cc_legato(fluid_channel_t *chan, int value)
 {
@@ -719,7 +717,7 @@ void fluid_channel_cc_legato(fluid_channel_t *chan, int value)
  * to trigger noteon/noteoff note when the musician starts to breath (noteon) and
  * stops to breath (noteoff).
  * @param chan  fluid_channel_t.
- * @param value, value of the CC Breath..
+ * @param value value of the CC Breath.
  */
 void fluid_channel_cc_breath_note_on_off(fluid_channel_t *chan, int value)
 {