Updated API doxygen documentation

src/sfizz.h

@@ -27,7 +27,13 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Synth handle
+ */
 typedef struct sfizz_synth_t sfizz_synth_t;
+/**
+ * @brief Oversampling factor
+ */
 typedef enum {
     SFIZZ_OVERSAMPLING_X1 = 1,
     SFIZZ_OVERSAMPLING_X2 = 2,
@@ -40,14 +46,13 @@ typedef enum {
  *             using sfizz_free(). The synth by default is set at 48 kHz
  *             and a maximum block size of 1024. You should change these values
  *             if they are not correct for your application.
- *
- * @return     sfizz_synth_t*
  */
 SFIZZ_EXPORTED_API sfizz_synth_t* sfizz_create_synth();
+
 /**
  * @brief      Frees an existing sfizz synth.
  *
- * @param      synth  The synth to destroy
+ * @param      synth  The synth to destroy.
  */
 SFIZZ_EXPORTED_API void sfizz_free(sfizz_synth_t* synth);
 
@@ -60,88 +65,76 @@ SFIZZ_EXPORTED_API void sfizz_free(sfizz_synth_t* synth);
  * @param      path   A null-terminated string representing a path to an SFZ
  *                    file.
  *
- * @return     true when file loading went OK.
+ * @return     @true when file loading went OK,
- * @return     false if some error occured while loading.
+ *             @false if some error occured while loading.
  */
 SFIZZ_EXPORTED_API bool sfizz_load_file(sfizz_synth_t* synth, const char* path);
 
 /**
- * @brief      Returns the number of regions in the currently loaded SFZ file.
+ * @brief      Return the number of regions in the currently loaded SFZ file.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     int the number of regions
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_regions(sfizz_synth_t* synth);
 /**
- * @brief      Returns the number of groups in the currently loaded SFZ file.
+ * @brief      Return the number of groups in the currently loaded SFZ file.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     int the number of groups
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_groups(sfizz_synth_t* synth);
 /**
- * @brief      Returns the number of masters in the currently loaded SFZ file.
+ * @brief      Return the number of masters in the currently loaded SFZ file.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     int the number of masters
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_masters(sfizz_synth_t* synth);
 /**
- * @brief      Returns the number of curves in the currently loaded SFZ file.
+ * @brief      Return the number of curves in the currently loaded SFZ file.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     int the number of curves
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_curves(sfizz_synth_t* synth);
 /**
  * @brief      Export a MIDI Name document describing the the currently loaded
  *             SFZ file.
  *
- * @param      synth        The synth
+ * @param      synth  The synth.
- * @param      model        the model name used if a non-empty string, otherwise generated
+ * @param      model  The model name used if a non-empty string, otherwise generated.
  *
- * @return     char* a newly allocated XML string, which must be freed after use
+ * @return     A newly allocated XML string, which must be freed after use.
  */
 SFIZZ_EXPORTED_API char* sfizz_export_midnam(sfizz_synth_t* synth, const char* model);
 /**
- * @brief      Returns the number of preloaded samples for the current SFZ file.
+ * @brief      Return the number of preloaded samples for the current SFZ file.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     int the number of preloaded samples
  */
 SFIZZ_EXPORTED_API size_t sfizz_get_num_preloaded_samples(sfizz_synth_t* synth);
 /**
- * @brief      Returns the number of active voices. Note that this function is a
+ * @brief      Return the number of active voices. Note that this function is a
  *             basic indicator and does not aim to be perfect. In particular, it
  *             runs on the calling thread so voices may well start or stop while
  *             the function is checking which voice is active.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     size_t the number of playing voices
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_active_voices(sfizz_synth_t* synth);
 
 /**
- * @brief      Sets the expected number of samples per block. If unsure, give an
+ * @brief      Set the expected number of samples per block. If unsure, give an
  *             upper bound since right now ugly things may happen if you go over
  *             this number.
  *
- * @param      synth              The synth
+ * @param      synth              The synth.
- * @param      samples_per_block  the number of samples per block
+ * @param      samples_per_block  The number of samples per block.
  */
 SFIZZ_EXPORTED_API void sfizz_set_samples_per_block(sfizz_synth_t* synth, int samples_per_block);
 /**
- * @brief      Sets the sample rate for the synth. This is the output sample
+ * @brief      Set the sample rate for the synth. This is the output sample
  *             rate. This setting does not affect the internal processing.
  *
  * @param      synth        The synth
- * @param      sample_rate  the sample rate
+ * @param      sample_rate  The sample rate.
  */
 SFIZZ_EXPORTED_API void sfizz_set_sample_rate(sfizz_synth_t* synth, float sample_rate);
 
@@ -150,10 +143,10 @@ SFIZZ_EXPORTED_API void sfizz_set_sample_rate(sfizz_synth_t* synth, float sample
  *             needs to happen before the call to sfizz_render_block in each
  *             block and should appear in order of the delays.
  *
- * @param      synth        The synth
+ * @param      synth        The synth.
- * @param      delay        the delay of the event in the block, in samples.
+ * @param      delay        The delay of the event in the block, in samples.
- * @param      note_number  the MIDI note number
+ * @param      note_number  The MIDI note number.
- * @param      velocity     the MIDI velocity
+ * @param      velocity     The MIDI velocity.
  */
 SFIZZ_EXPORTED_API void sfizz_send_note_on(sfizz_synth_t* synth, int delay, int note_number, char velocity);
 
@@ -164,10 +157,10 @@ SFIZZ_EXPORTED_API void sfizz_send_note_on(sfizz_synth_t* synth, int delay, int
  *             As per the SFZ spec the velocity of note-off events is usually replaced by
  *             the note-on velocity.
  *
- * @param      synth        The synth
+ * @param      synth        The synth.
- * @param      delay        the delay of the event in the block, in samples.
+ * @param      delay        The delay of the event in the block, in samples.
- * @param      note_number  the MIDI note number
+ * @param      note_number  The MIDI note number.
- * @param      velocity     the MIDI velocity
+ * @param      velocity     The MIDI velocity.
  */
 SFIZZ_EXPORTED_API void sfizz_send_note_off(sfizz_synth_t* synth, int delay, int note_number, char velocity);
 
@@ -176,38 +169,39 @@ SFIZZ_EXPORTED_API void sfizz_send_note_off(sfizz_synth_t* synth, int delay, int
  *             to happen before the call to sfizz_render_block in each block and
  *             should appear in order of the delays.
  *
- * @param      synth      The synth
+ * @param      synth      The synth.
- * @param      delay      the delay of the event in the block, in samples.
+ * @param      delay      The delay of the event in the block, in samples.
- * @param      cc_number  the MIDI CC number
+ * @param      cc_number  The MIDI CC number.
- * @param      cc_value   the MIDI CC value
+ * @param      cc_value   The MIDI CC value.
  */
 SFIZZ_EXPORTED_API void sfizz_send_cc(sfizz_synth_t* synth, int delay, int cc_number, char cc_value);
+
 /**
  * @brief      Send a pitch wheel event. As with all MIDI events, this needs
  *             to happen before the call to sfizz_render_block in each block and
  *             should appear in order of the delays.
  *
- * @param      synth    The synth
+ * @param      synth    The synth.
- * @param      delay    The delay
+ * @param      delay    The delay.
- * @param      pitch    The pitch
+ * @param      pitch    The pitch.
  */
 SFIZZ_EXPORTED_API void sfizz_send_pitch_wheel(sfizz_synth_t* synth, int delay, int pitch);
 
 /**
- * @brief Send an aftertouch event. (CURRENTLY UNIMPLEMENTED)
+ * @brief      Send an aftertouch event. (CURRENTLY UNIMPLEMENTED)
  *
- * @param synth
+ * @param      synth
- * @param delay
+ * @param      delay
- * @param aftertouch
+ * @param      aftertouch
  */
 SFIZZ_EXPORTED_API void sfizz_send_aftertouch(sfizz_synth_t* synth, int delay, char aftertouch);
 
 /**
  * @brief      Send a tempo event. (CURRENTLY UNIMPLEMENTED)
  *
- * @param      synth                The synth
+ * @param      synth                The synth.
- * @param      delay                The delay
+ * @param      delay                The delay.
- * @param      seconds_per_quarter  The seconds per quarter
+ * @param      seconds_per_quarter  The seconds per quarter.
  */
 SFIZZ_EXPORTED_API void sfizz_send_tempo(sfizz_synth_t* synth, int delay, float seconds_per_quarter);
 
@@ -219,11 +213,11 @@ SFIZZ_EXPORTED_API void sfizz_send_tempo(sfizz_synth_t* synth, int delay, float
  *             block. The synth will memorize the inputs and render sample
  *             accurates envelopes depending on the input events passed to it.
  *
- * @param      synth         The synth
+ * @param      synth         The synth.
- * @param      channels      pointers to the left and right channel of the
+ * @param      channels      Pointers to the left and right channel of the
- *                           output
+ *                           output.
- * @param      num_channels  should be equal to 2 for the time being.
+ * @param      num_channels  Should be equal to 2 for the time being.
- * @param      num_frames    number of frames to fill. This should be less than
+ * @param      num_frames    Number of frames to fill. This should be less than
  *                           or equal to the expected samples_per_block.
  */
 SFIZZ_EXPORTED_API void sfizz_render_block(sfizz_synth_t* synth, float** channels, int num_channels, int num_frames);
@@ -232,18 +226,16 @@ SFIZZ_EXPORTED_API void sfizz_render_block(sfizz_synth_t* synth, float** channel
  * @brief      Get the size of the preloaded data. This returns the number of
  *             floats used in the preloading buffers.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     the preloaded data size in sizeof(floats)
  */
 SFIZZ_EXPORTED_API unsigned int sfizz_get_preload_size(sfizz_synth_t* synth);
 /**
- * @brief      Sets the size of the preloaded data in number of floats (not
+ * @brief      Set the size of the preloaded data in number of floats (not
  *             bytes). This will disable the callbacks for the duration of the
  *             load.
  *
- * @param      synth         The synth
+ * @param      synth         The synth.
- * @param[in]  preload_size  The preload size
+ * @param[in]  preload_size  The preload size.
  */
 SFIZZ_EXPORTED_API void sfizz_set_preload_size(sfizz_synth_t* synth, unsigned int preload_size);
 
@@ -252,9 +244,7 @@ SFIZZ_EXPORTED_API void sfizz_set_preload_size(sfizz_synth_t* synth, unsigned in
  *             the engine, not the output or expected rate of the calling
  *             function. For the latter use the `get_sample_rate()` functions.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     The internal sample rate of the engine
  */
 SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor(sfizz_synth_t* synth);
 /**
@@ -272,51 +262,46 @@ SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor(sfi
  *             to compensate for the memory increase, but the full loading will
  *             need to take place anyway.
  *
- * @param      synth         The synth
+ * @param      synth         The synth.
- * @param[in]  preload_size  The preload size
+ * @param[in]  oversampling  The oversampling factor.
  *
- * @return     True if the oversampling factor was correct
+ * @return     @true if the oversampling factor was correct, @false otherwise.
  */
 SFIZZ_EXPORTED_API bool sfizz_set_oversampling_factor(sfizz_synth_t* synth, sfizz_oversampling_factor_t oversampling);
 
 /**
  * @brief      Set the global instrument volume.
  *
- * @param      synth   The synth
+ * @param      synth   The synth.
- * @param      volume  the new volume
+ * @param      volume  The new volume.
  */
 SFIZZ_EXPORTED_API void sfizz_set_volume(sfizz_synth_t* synth, float volume);
 
 /**
- * @brief      Get the global instrument volume.
+ * @brief      Return the global instrument volume.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     float the instrument volume
  */
 SFIZZ_EXPORTED_API float sfizz_get_volume(sfizz_synth_t* synth);
 
 /**
- * @brief      Sets the number of voices used by the synth
+ * @brief      Set the number of voices used by the synth.
  *
- * @param      synth       The synth
+ * @param      synth       The synth.
- * @param      num_voices  The number voices
+ * @param      num_voices  The number of voices.
  */
 SFIZZ_EXPORTED_API void sfizz_set_num_voices(sfizz_synth_t* synth, int num_voices);
 /**
- * @brief Returns the number of voices
+ * @brief      Return the number of voices.
  *
- * @param synth
+ * @param      synth  The synth.
- * @return num_voices
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_voices(sfizz_synth_t* synth);
 
 /**
- * @brief      Get the number of allocated buffers from the synth.
+ * @brief      Return the number of allocated buffers from the synth.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     The number of buffers held by the synth
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_buffers(sfizz_synth_t* synth);
 /**
@@ -324,73 +309,70 @@ SFIZZ_EXPORTED_API int sfizz_get_num_buffers(sfizz_synth_t* synth);
  *             value can be less than the actual memory usage since it only
  *             counts the buffer objects managed by sfizz.
  *
- * @param      synth  The synth
+ * @param      synth  The synth.
- *
- * @return     The number of bytes held by the synth in buffers;
  */
 SFIZZ_EXPORTED_API int sfizz_get_num_bytes(sfizz_synth_t* synth);
 
 /**
- * @brief Enables freewheeling on the synth.
+ * @brief      Enable freewheeling on the synth.
  *
- * @param synth
+ * @param      synth  The synth.
  */
 SFIZZ_EXPORTED_API void sfizz_enable_freewheeling(sfizz_synth_t* synth);
 /**
- * @brief Disables freewheeling on the synth.
+ * @brief      Disable freewheeling on the synth.
  *
- * @param synth
+ * @param      synth  The synth.
  */
 SFIZZ_EXPORTED_API void sfizz_disable_freewheeling(sfizz_synth_t* synth);
 /**
- * @brief Get a comma separated list of unknown opcodes. The caller has to free()
+ * @brief      Return a comma separated list of unknown opcodes.
- * the string returned. This function allocates memory, do not call on the
+ *             The caller has to free() the string returned.
- * audio thread.
+ *             This function allocates memory, do not call on the audio thread.
  *
- * @param synth
+ * @param      synth  The synth.
- * @return char*
  */
 SFIZZ_EXPORTED_API char* sfizz_get_unknown_opcodes(sfizz_synth_t* synth);
 
 /**
- * @brief Check if the SFZ should be reloaded.
+ * @brief      Check if the SFZ should be reloaded.
+ *             Depending on the platform this can create file descriptors.
  *
- * Depending on the platform this can create file descriptors.
+ * @param      synth  The synth.
  *
- * @param synth
+ * @return     @true if any included files (including the root file) have
- * @return true if any included files (including the root file) have
+ *             been modified since the sfz file was loaded, @false otherwise.
- *              been modified since the sfz file was loaded.
- * @return false
  */
 SFIZZ_EXPORTED_API bool sfizz_should_reload_file(sfizz_synth_t* synth);
 
 /**
- * @brief Enable logging of timings to sidecar CSV files. This can produce
+ * @brief      Enable logging of timings to sidecar CSV files. This can produce
- * many outputs so use with caution.
+ *             many outputs so use with caution.
  *
- * @param synth
+ * @param      synth  The synth.
  */
 SFIZZ_EXPORTED_API void sfizz_enable_logging(sfizz_synth_t* synth);
 
 /**
- * @brief Disable logging
+ * @brief      Disable logging.
  *
- * @param synth
+ * @param      synth  The synth.
  */
 SFIZZ_EXPORTED_API void sfizz_disable_logging(sfizz_synth_t* synth);
 
 /**
- * @brief Enable logging of timings to sidecar CSV files. This can produce
+ * @brief      Enable logging of timings to sidecar CSV files. This can produce
- * many outputs so use with caution.
+ *             many outputs so use with caution.
  *
- * @param synth
+ * @param      synth  The synth.
+ * @param      prefix The prefix.
  */
 SFIZZ_EXPORTED_API void sfizz_set_logging_prefix(sfizz_synth_t* synth, const char* prefix);
 
 /**
- * @brief Shuts down the current processing, clear buffers and reset the voices.
+ * @brief      Shuts down the current processing, clear buffers and reset the voices.
  *
- * @param synth
+ * @param      synth  The synth.
  */
 SFIZZ_EXPORTED_API void sfizz_all_sound_off(sfizz_synth_t* synth);
 

src/sfizz.hpp

@@ -4,6 +4,11 @@
 // license. You should have receive a LICENSE.md file along with the code.
 // If not, contact the sfizz maintainers at https://github.com/sfztools/sfizz
 
+/**
+  @file
+  @brief sfizz public C++ API
+*/
+
 #include <string>
 #include <vector>
 #include <memory>
@@ -21,6 +26,9 @@
 namespace sfz
 {
 class Synth;
+/**
+ * @brief Main class
+ */
 class SFIZZ_EXPORTED_API Sfizz
 {
 public:
@@ -32,6 +40,7 @@ public:
      */
     Sfizz();
     ~Sfizz();
+
     /**
      * @brief Empties the current regions and load a new SFZ file into the synth.
      *
@@ -39,68 +48,70 @@ public:
      * UI thread for example, although it may generate a click. However it is
      * not reentrant, so you should not call it from concurrent threads.
      *
-     * @param file
+     * @param path The path to the file to load, as string.
-     * @return true
+     *
-     * @return false if the file was not found or no regions were loaded.
+     * @return @false if the file was not found or no regions were loaded,
+     *         @true otherwise.
      */
     bool loadSfzFile(const std::string& path);
+
     /**
-     * @brief Get the current number of regions loaded
+     * @brief Return the current number of regions loaded.
-     *
-     * @return int
      */
     int getNumRegions() const noexcept;
+
     /**
-     * @brief Get the current number of groups loaded
+     * @brief Return the current number of groups loaded.
-     *
-     * @return int
      */
     int getNumGroups() const noexcept;
+
     /**
-     * @brief Get the current number of masters loaded
+     * @brief Return the current number of masters loaded.
-     *
-     * @return int
      */
     int getNumMasters() const noexcept;
+
     /**
-     * @brief Get the current number of curves loaded
+     * @brief Return the current number of curves loaded.
-     *
-     * @return int
      */
     int getNumCurves() const noexcept;
-    const std::vector<std::string>& getUnknownOpcodes() const noexcept;
+
     /**
-     * @brief Get the number of preloaded samples in the synth
+     * @brief Return a list of unsupported opcodes, if any.
-     *
+     */
-     * @return size_t
+    const std::vector<std::string>& getUnknownOpcodes() const noexcept;
+
+    /**
+     * @brief Return the number of preloaded samples in the synth.
      */
     size_t getNumPreloadedSamples() const noexcept;
+
     /**
      * @brief Set the maximum size of the blocks for the callback. The actual
      * size can be lower in each callback but should not be larger
      * than this value.
      *
-     * @param samplesPerBlock
+     * @param samplesPerBlock The number of samples per block.
      */
     void setSamplesPerBlock(int samplesPerBlock) noexcept;
+
     /**
      * @brief Set the sample rate. If you do not call it it is initialized
      * to sfz::config::defaultSampleRate.
      *
-     * @param sampleRate
+     * @param sampleRate The sample rate.
      */
     void setSampleRate(float sampleRate) noexcept;
+
     /**
-     * @brief Get the current value for the volume, in dB.
+     * @brief Return the current value for the volume, in dB.
-     *
-     * @return float
      */
     float getVolume() const noexcept;
-    /**
+
+     /**
      * @brief Set the value for the volume. This value will be
      * clamped within sfz::default::volumeRange.
      *
-     * @param volume
+     * @param volume The new volume.
      */
     void setVolume(float volume) noexcept;
 
@@ -109,125 +120,122 @@ public:
      *
      * @param delay the delay at which the event occurs; this should be lower
      *              than the size of the block in the next call to renderBlock().
-     * @param noteNumber the midi note number
+     * @param noteNumber the midi note number.
-     * @param velocity the midi note velocity
+     * @param velocity the midi note velocity.
      */
     void noteOn(int delay, int noteNumber, uint8_t velocity) noexcept;
+
     /**
      * @brief Send a note off event to the synth
      *
      * @param delay the delay at which the event occurs; this should be lower
      *              than the size of the block in the next call to renderBlock().
-     * @param noteNumber the midi note number
+     * @param noteNumber the midi note number.
-     * @param velocity the midi note velocity
+     * @param velocity the midi note velocity.
      */
     void noteOff(int delay, int noteNumber, uint8_t velocity) noexcept;
+
     /**
      * @brief Send a CC event to the synth
      *
      * @param delay the delay at which the event occurs; this should be lower than the size of
      *              the block in the next call to renderBlock().
-     * @param ccNumber the cc number
+     * @param ccNumber the cc number.
-     * @param ccValue the cc value
+     * @param ccValue the cc value.
      */
     void cc(int delay, int ccNumber, uint8_t ccValue) noexcept;
+
     /**
      * @brief Send a pitch bend event to the synth
      *
      * @param delay the delay at which the event occurs; this should be lower
      *              than the size of the block in the next call to
      *              renderBlock().
-     * @param pitch the pitch value centered between -8192 and 8192
+     * @param pitch the pitch value centered between -8192 and 8192.
      */
     void pitchWheel(int delay, int pitch) noexcept;
+
     /**
-     * @brief Send a aftertouch event to the synth
+     * @brief Send a aftertouch event to the synth. (CURRENTLY UNIMPLEMENTED)
      *
      * @param delay the delay at which the event occurs; this should be lower than the size of
      *              the block in the next call to renderBlock().
-     * @param aftertouch the aftertouch value
+     * @param aftertouch the aftertouch value.
      */
     void aftertouch(int delay, uint8_t aftertouch) noexcept;
+
     /**
-     * @brief Send a tempo event to the synth
+     * @brief Send a tempo event to the synth. (CURRENTLY UNIMPLEMENTED)
      *
      * @param delay the delay at which the event occurs; this should be lower than the size of
      *              the block in the next call to renderBlock().
-     * @param secondsPerQuarter the new period of the quarter note
+     * @param secondsPerQuarter the new period of the quarter note.
      */
     void tempo(int delay, float secondsPerQuarter) noexcept;
+
     /**
      * @brief Render an block of audio data in the buffer. This call will reset
      * the synth in its waiting state for the next batch of events. The buffers must
      * be float[numSamples][numOutputs * 2].
      *
-     * @param buffers the buffers to write the next block into
+     * @param buffers the buffers to write the next block into.
-     * @param numSamples the number of stereo frames in the block
+     * @param numFrames the number of stereo frames in the block.
-     * @param numOutputs the number of stereo outputs
+     * @param numOutputs the number of stereo outputs.
      */
     void renderBlock(float** buffers, size_t numFrames, int numOutputs = 1) noexcept;
 
     /**
-     * @brief Get the number of active voices
+     * @brief Return the number of active voices.
-     *
-     * @return int
      */
     int getNumActiveVoices() const noexcept;
+
     /**
-     * @brief Get the total number of voices in the synth (the polyphony)
+     * @brief Return the total number of voices in the synth (the polyphony).
-     *
-     * @return int
      */
     int getNumVoices() const noexcept;
+
     /**
-     * @brief Change the number of voices (the polyphony)
+     * @brief Change the number of voices (the polyphony).
      *
-     * @param numVoices
+     * @param numVoices The number of voices.
      */
     void setNumVoices(int numVoices) noexcept;
 
-        /**
+    /**
      * @brief Set the oversampling factor to a new value. This will disable all callbacks
      * kill all the voices, and trigger a reloading of every file in the FilePool under
      * the new oversampling.
      *
-     * @param factor
+     * @param factor The oversampling factor.
-     * @return true if the factor did indeed change
+     *
+     * @return @true if the factor did indeed change, @false otherwise.
      */
     bool setOversamplingFactor(int factor) noexcept;
 
     /**
-     * @brief get the current oversampling factor
+     * @brief Return the current oversampling factor.
-     *
-     * @return Oversampling
      */
     int getOversamplingFactor() const noexcept;
 
     /**
      * @brief Set the preloaded file size. This will disable the callback.
      *
-     * @param factor
+     * @param preloadSize  The preload size.
      */
     void setPreloadSize(uint32_t preloadSize) noexcept;
 
     /**
-     * @brief get the current preloaded file size
+     * @brief Return the current preloaded file size.
-     *
-     * @return Oversampling
      */
     uint32_t getPreloadSize() const noexcept;
 
     /**
-     * @brief      Gets the number of allocated buffers.
+     * @brief Return the number of allocated buffers.
-     *
-     * @return     The allocated buffers.
      */
     int getAllocatedBuffers() const noexcept;
 
     /**
-     * @brief      Gets the number of bytes allocated through the buffers
+     * @brief Return the number of bytes allocated through the buffers.
-     *
-     * @return     The allocated bytes.
      */
     int getAllocatedBytes() const noexcept;
 
@@ -235,55 +243,59 @@ public:
      * @brief Enable freewheeling on the synth. This will wait for background
      * loaded files to finish loading before each render callback to ensure that
      * there will be no dropouts.
-     *
      */
     void enableFreeWheeling() noexcept;
+
     /**
      * @brief Disable freewheeling on the synth. You should disable freewheeling
      * before live use of the plugin otherwise the audio thread will lock.
      *
      */
     void disableFreeWheeling() noexcept;
+
     /**
      * @brief Check if the SFZ should be reloaded.
      *
      * Depending on the platform this can create file descriptors.
      *
-     * @return true if any included files (including the root file) have
+     * @return @true if any included files (including the root file) have
-     *              been modified since the sfz file was loaded.
+     *         been modified since the sfz file was loaded, @false otherwise.
-     * @return false
      */
     bool shouldReloadFile();
+
     /**
      * @brief Enable logging of timings to sidecar CSV files. This can produce
      * many outputs so use with caution.
      *
-     * @param prefix the file prefix to use for logging
+     * @param prefix the file prefix to use for logging.
      */
     void enableLogging() noexcept;
+
     /**
      * @brief Enable logging of timings to sidecar CSV files. This can produce
      * many outputs so use with caution.
      *
-     * @param prefix the file prefix to use for logging
+     * @param prefix the file prefix to use for logging.
      */
     void enableLogging(const std::string& prefix) noexcept;
+
     /**
-     * @brief Set the logging prefix
+     * @brief Set the logging prefix.
      *
      * @param prefix
      */
     void setLoggingPrefix(const std::string& prefix) noexcept;
+
     /**
-     * @brief Disable logging;
+     * @brief Disable logging.
-     *
      */
     void disableLogging() noexcept;
+
     /**
      * @brief Shuts down the current processing, clear buffers and reset the voices.
-     *
      */
     void allSoundOff() noexcept;
+
 private:
     std::unique_ptr<sfz::Synth> synth;
 };