From: Robin Gareus Date: Mon, 30 Sep 2019 03:33:44 +0000 (+0200) Subject: Fix some more doxygen warnings X-Git-Url: https://main.carlh.net/gitweb/?a=commitdiff_plain;h=ee54b13d6d5bf14948aea6d2f55abc2919c038d1;p=ardour.git Fix some more doxygen warnings --- diff --git a/libs/ardour/ardour/dsp_filter.h b/libs/ardour/ardour/dsp_filter.h index 1f13cceb61..e557c39808 100644 --- a/libs/ardour/ardour/dsp_filter.h +++ b/libs/ardour/ardour/dsp_filter.h @@ -192,7 +192,7 @@ namespace ARDOUR { namespace DSP { * * @param data pointer to control-data array * @param val target value - * @param array length + * @param n_samples array length */ void ctrl (float *data, const float val, const uint32_t n_samples); /** update filter cut-off frequency @@ -282,7 +282,7 @@ namespace ARDOUR { namespace DSP { /** query * @param bin the frequency bin 0 .. window_size / 2 - * @param norm gain factor (set equal to @bin for 1/f normalization) + * @param norm gain factor (set equal to \param bin for 1/f normalization) * @return signal power at given bin (in dBFS) */ float power_at_bin (const uint32_t bin, const float norm = 1.f) const; diff --git a/libs/ardour/ardour/fluid_synth.h b/libs/ardour/ardour/fluid_synth.h index 2b9af71a91..e37a27419e 100644 --- a/libs/ardour/ardour/fluid_synth.h +++ b/libs/ardour/ardour/fluid_synth.h @@ -34,6 +34,7 @@ namespace ARDOUR { /** instantiate a Synth * * @param samplerate samplerate + * @param polyphony polyphony */ FluidSynth (float samplerate, int polyphony = 32); ~FluidSynth (); diff --git a/libs/ardour/ardour/lua_api.h b/libs/ardour/ardour/lua_api.h index 9f5e0d0aa1..1407b3cd3b 100644 --- a/libs/ardour/ardour/lua_api.h +++ b/libs/ardour/ardour/lua_api.h @@ -81,6 +81,7 @@ namespace ARDOUR { namespace LuaAPI { * @param s Session Handle * @param id Plugin Name, ID or URI * @param type Plugin Type + * @param preset name of plugin-preset to load, leave empty "" to not load any preset after instantiation * @returns Processor or nil */ boost::shared_ptr new_plugin (ARDOUR::Session *s, const std::string& id, ARDOUR::PluginType type, const std::string& preset = ""); @@ -92,7 +93,7 @@ namespace ARDOUR { namespace LuaAPI { * @param value value to set * @returns true on success, false on error or out-of-bounds value */ - bool set_processor_param (boost::shared_ptr proc, uint32_t which, float val); + bool set_processor_param (boost::shared_ptr proc, uint32_t which, float value); /** get a plugin control parameter value * @@ -116,16 +117,16 @@ namespace ARDOUR { namespace LuaAPI { * * This is a wrapper around set_processor_param which looks up the Processor by plugin-insert. * - * @param proc Plugin-Insert + * @param pi Plugin-Insert * @param which control-input to set (starting at 0) * @param value value to set * @returns true on success, false on error or out-of-bounds value */ - bool set_plugin_insert_param (boost::shared_ptr pi, uint32_t which, float val); + bool set_plugin_insert_param (boost::shared_ptr pi, uint32_t which, float value); /** get a plugin control parameter value * - * @param proc Plugin-Insert + * @param pi Plugin-Insert * @param which control port to query (starting at 0, including ports of type input and output) * @param ok boolean variable contains true or false after call returned. to be checked by caller before using value. * @returns value @@ -250,12 +251,12 @@ namespace ARDOUR { namespace LuaAPI { * * If the plugin is not yet initialized, initialize() is called. * - * if @cb is not nil, it is called with the immediate + * if \param fn is not nil, it is called with the immediate * Vamp::Plugin::Features on every process call. * * @param r readable * @param channel channel to process - * @param fn lua callback function + * @param fn lua callback function or nil * @return 0 on success */ int analyze (boost::shared_ptr r, uint32_t channel, luabridge::LuaRef fn); diff --git a/libs/ardour/ardour/port_manager.h b/libs/ardour/ardour/port_manager.h index 46e6dc77ad..a991d4fafd 100644 --- a/libs/ardour/ardour/port_manager.h +++ b/libs/ardour/ardour/port_manager.h @@ -189,8 +189,7 @@ class LIBARDOUR_API PortManager boost::shared_ptr register_port (DataType type, const std::string& portname, bool input, bool async = false, PortFlags extra_flags = PortFlags (0)); void port_registration_failure (const std::string& portname); - /** List of ports to be used between ::cycle_start() and ::cycle_end() - */ + /** List of ports to be used between \ref cycle_start() and \ref cycle_end() */ boost::shared_ptr _cycle_ports; void silence (pframes_t nframes, Session *s = 0); diff --git a/libs/ardour/ardour/processor.h b/libs/ardour/ardour/processor.h index a834a8c71a..e0b797b1b8 100644 --- a/libs/ardour/ardour/processor.h +++ b/libs/ardour/ardour/processor.h @@ -88,10 +88,17 @@ class LIBARDOUR_API Processor : public SessionObject, public Automatable, public virtual int set_block_size (pframes_t /*nframes*/) { return 0; } virtual bool requires_fixed_sized_buffers() const { return false; } - /** @param result_required true if, on return from this method, @a bufs is required to contain valid data; - * if false, the method need not bother writing to @a bufs if it doesn't want to. + /** The main process function for processors + * + * @param bufs bufferset of data to process in-place + * @param start_sample absolute timeline position in audio-samples to commence processing (latency compensated) + * @param end_sample absolute timeline position in audio-samples, usually start_sample +/- \param nframes + * @param speed transport speed. usually -1, 0, +1 + * @param nframes number of audio samples to process + * @param result_required true if, on return from this method, \param bufs is required to contain valid data; + * if false, the method need not bother writing to @a bufs if it doesn't want to. */ - virtual void run (BufferSet& /*bufs*/, samplepos_t /*start_sample*/, samplepos_t /*end_sample*/, double speed, pframes_t /*nframes*/, bool /*result_required*/) {} + virtual void run (BufferSet& bufs, samplepos_t start_sample, samplepos_t end_sample, double speed, pframes_t nframes, bool result_required) {} virtual void silence (samplecnt_t nframes, samplepos_t start_sample) { automation_run (start_sample, nframes); } virtual void activate () { _pending_active = true; ActiveChanged(); } diff --git a/libs/ardour/ardour/tempo.h b/libs/ardour/ardour/tempo.h index 47ee53038e..9e5124f1af 100644 --- a/libs/ardour/ardour/tempo.h +++ b/libs/ardour/ardour/tempo.h @@ -389,23 +389,24 @@ class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible TempoSection* next_tempo_section (TempoSection*) const; /** add a tempo section locked to pls. ignored values will be set in recompute_tempi() - * @param pulse pulse position of new section. ignored if pls == AudioTime - * @param sample frame position of new section. ignored if pls == MusicTime - * @param type type of new tempo section (Ramp, Constant) + * @param pulse pulse position of new section. ignored if \param pls == AudioTime + * @param sample frame position of new section. ignored if \param pls == MusicTime + * @param pls the position lock style */ TempoSection* add_tempo (const Tempo&, const double& pulse, const samplepos_t sample, PositionLockStyle pls); - /** add a meter section locked to pls.. ignored values will be set in recompute_meters() + /** add a meter section locked to \param pls . ignored values will be set in recompute_meters() * @param meter the Meter to be added * @param where bbt position of new section - * @param sample frame position of new section. ignored if pls == MusicTime - * note that @sample may also be ignored if it would create an un-solvable map + * @param sample frame position of new section. ignored if \param pls == MusicTime + * + * note that \param sample may also be ignored if it would create an un-solvable map * (previous audio-locked tempi may place the requested beat at an earlier time than sample) * in which case the new meter will be placed at the specified BBT. - * @param pls the position lock style + * @param pls the position lock style * * adding an audio-locked meter will add a meter-locked tempo section at the meter position. - * the meter-locked tempo tempo will be the Tempo at @beat + * the meter-locked tempo tempo will be the Tempo at the beat */ MeterSection* add_meter (const Meter& meter, const Timecode::BBT_Time& where, samplepos_t sample, PositionLockStyle pls); diff --git a/libs/pbd/pbd/file_utils.h b/libs/pbd/pbd/file_utils.h index b834587ae1..46e3ab1849 100644 --- a/libs/pbd/pbd/file_utils.h +++ b/libs/pbd/pbd/file_utils.h @@ -50,10 +50,9 @@ get_paths (std::vector& result, /** * Get a list of files in a Searchpath. - * @note paths in result will be absolute. * - * @param path A Searchpath - * @param result A vector of paths to files. + * @param paths A Searchpath + * @param result A vector of absolute paths to files. */ LIBPBD_API void get_files (std::vector& result, @@ -109,11 +108,11 @@ find_file (const Searchpath& search_path, /** * Find files in paths that match a regular expression - * @note This function does not recurse. * - * @param result A vector in which to place the resulting matches. + * @param results A vector in which to place the resulting matches. * @param paths A Searchpath * @param regexp A regular expression + * @param recurse Search directories recursively */ LIBPBD_API void find_files_matching_regex (std::vector& results, @@ -125,7 +124,7 @@ find_files_matching_regex (std::vector& results, * Find paths in a Searchpath that match a supplied filter(functor) * @note results include files and directories. * - * @param result A vector in which to place the resulting matches. + * @param results A vector in which to place the resulting matches. * @param paths A Searchpath * @param filter A functor to use to filter paths * @param arg additonal argument to filter if required @@ -146,7 +145,7 @@ find_paths_matching_filter (std::vector& results, * Find paths in a Searchpath that match a supplied filter(functor) * @note results include only files. * - * @param result A vector in which to place the resulting matches. + * @param results A vector in which to place the resulting matches. * @param paths A Searchpath * @param filter A functor to use to filter paths * @param arg additonal argument to filter if required @@ -183,9 +182,9 @@ LIBPBD_API void copy_files(const std::string & from_path, const std::string & to LIBPBD_API void copy_recurse(const std::string & from_path, const std::string & to_dir); /** - * Update the access and modification times of file at @path, creating file if it - * doesn't already exist. - * @path file path to touch + * Update the access and modification times of file at path, creating file + * if it doesn't already exist. + * @param path file path to touch * @return true if file exists or was created and access time updated. */ LIBPBD_API bool touch_file (const std::string& path); @@ -202,7 +201,7 @@ LIBPBD_API bool hard_link (const std::string& existing_file, const std::string& LIBPBD_API std::string get_absolute_path (const std::string &); /** - * The equivalent of ::realpath on POSIX systems, on Windows hard + * The equivalent of realpath on POSIX systems, on Windows hard * links/junctions etc are not resolved. */ LIBPBD_API std::string canonical_path (const std::string& path); @@ -240,7 +239,7 @@ LIBPBD_API bool exists_and_writable(const std::string & p); * * @param dir The directory to clear of files. * @param size of removed files in bytes. - * @param list of files that were removed. + * @param removed_files list of files that were removed. */ LIBPBD_API int clear_directory (const std::string& dir, size_t* size = 0, std::vector* removed_files = 0); @@ -269,12 +268,11 @@ LIBPBD_API void remove_directory (const std::string& dir); */ LIBPBD_API std::string tmp_writable_directory (const char* domain, const std::string& prefix); -/** If @param path exists, unlink it. If it doesn't exist, create it. +/** If \param path exists, unlink it. If it doesn't exist, create it. * * @return zero if required action was successful, non-zero otherwise. */ - -LIBPBD_API int toggle_file_existence (std::string const &); +LIBPBD_API int toggle_file_existence (std::string const & path); } // namespace PBD diff --git a/libs/pbd/pbd/system_exec.h b/libs/pbd/pbd/system_exec.h index c40ecc3a8a..9247323786 100644 --- a/libs/pbd/pbd/system_exec.h +++ b/libs/pbd/pbd/system_exec.h @@ -109,9 +109,10 @@ class LIBPBD_API SystemExec * creates an argv array from the given command string, splitting into * parameters at spaces. * "\ " is non-splitting space, "\\" (and "\" at end of command) as "\", - * for "%", is looked up in subs and the corresponding string + * for "%", \ is looked up in subs and the corresponding string * substituted. "%%" (and "%" at end of command) - * returns an argv array suitable for creating a new SystemExec with + * + * @returns an argv array suitable for creating a new SystemExec with */ SystemExec (std::string command, const std::map subs); @@ -135,10 +136,11 @@ class LIBPBD_API SystemExec * '1': ignore STDERR of child-program * '2': merge STDERR into STDOUT and send it with the * ReadStdout signal. + * @param _vfork_exec_wrapper path to vfork-wrapper binary * @return If the process is already running or was launched successfully * the function returns zero (0). A negative number indicates an error. */ - int start (StdErrMode, const char *_vfork_exec_wrapper); + int start (StdErrMode stderr_mode, const char *_vfork_exec_wrapper); /** kill running child-process * * if a child process exists trt to shut it down by closing its STDIN. @@ -158,7 +160,7 @@ class LIBPBD_API SystemExec * * This function is only useful if you want to control application * termination yourself (eg timeouts or progress-dialog). - * @param option flags - see waitpid manual + * @param options flags - see waitpid manual * @return status info from waitpid call (not waitpid's return value) * or -1 if the child-program is not running. */ @@ -183,7 +185,7 @@ class LIBPBD_API SystemExec * @param bytes length of data to write * @return number of bytes written. */ - size_t write_to_stdin (const void* d, size_t bytes=0); + size_t write_to_stdin (const void* data, size_t bytes=0); /** The ReadStdout signal is emitted when the application writes to STDOUT. * it passes the written data and its length in bytes as arguments to the bound