Fix several doxygen warnings (#1790)

Author: derselbst

.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/.gitignore

@@ -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

doc/wiki/BuildingForAndroid.md

@@ -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/bindings/fluid_cmd.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_chorus.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;