Fix remaining doxygen warnings (!)

16 files changed, 102 insertions, 58 deletions

diff --git a/libs/ardour/ardour/bundle.h b/libs/ardour/ardour/bundle.h
index 068c92c1f7..88f095dd33 100644
--- a/libs/ardour/ardour/bundle.h
+++ b/libs/ardour/ardour/bundle.h
@@ -77,10 +77,10 @@ class LIBARDOUR_API Bundle : public PBD::ScopedConnectionList
 	ChanCount nchannels () const;
 	uint32_t n_total () const; /* shortcut for nchannels().n_total() */
 
-	/** @param Channel index.
+	/** @param c Channel index.
 	 *  @return Ports associated with this channel.
 	 */
-	PortList const & channel_ports (uint32_t) const;
+	PortList const & channel_ports (uint32_t c) const;
 
 	void add_channel (std::string const &, DataType);
 	void add_channel (std::string const &, DataType, std::string const &);
diff --git a/libs/ardour/ardour/element_import_handler.h b/libs/ardour/ardour/element_import_handler.h
index 6a7ea72531..98eda088a2 100644
--- a/libs/ardour/ardour/element_import_handler.h
+++ b/libs/ardour/ardour/element_import_handler.h
@@ -48,6 +48,7 @@ class LIBARDOUR_API ElementImportHandler
 	 * and create respective Elements stored in elements.
 	 *
 	 * @param source XML tree to be parsed
+	 * @param session The Session
 	 * @see elements
 	 */
 	ElementImportHandler (XMLTree const & source, ARDOUR::Session & session)
diff --git a/libs/ardour/ardour/meter.h b/libs/ardour/ardour/meter.h
index 9e5fa9536e..332b05cc2d 100644
--- a/libs/ardour/ardour/meter.h
+++ b/libs/ardour/ardour/meter.h
@@ -91,7 +91,7 @@ private:
 
 	/** The number of meters that we are currently handling;
 	 *  may be different to _configured_input and _configured_output
-	 *  as it can be altered outside a ::configure_io by ::reflect_inputs.
+	 *  as it can be altered outside a \ref configure_io by \ref reflect_inputs .
 	 */
 	ChanCount current_meters;
 
diff --git a/libs/ardour/ardour/midi_playlist.h b/libs/ardour/ardour/midi_playlist.h
index f6e0c77b4d..82ec7b65e1 100644
--- a/libs/ardour/ardour/midi_playlist.h
+++ b/libs/ardour/ardour/midi_playlist.h
@@ -78,6 +78,7 @@ public:
 	 * @param chan_n Must be 0 (this is the audio-style "channel", where each
 	 * channel is backed by a separate region, not MIDI channels, which all
 	 * exist in the same region and are not handled here).
+	 * @param filter Channel filter to apply or NULL to disable filter
 	 * @return The number of samples read (time, not an event count).
 	 */
 	samplecnt_t read (Evoral::EventSink<samplepos_t>& buf,
diff --git a/libs/ardour/ardour/midi_source.h b/libs/ardour/ardour/midi_source.h
index a08845639b..0334b95b06 100644
--- a/libs/ardour/ardour/midi_source.h
+++ b/libs/ardour/ardour/midi_source.h
@@ -56,12 +56,13 @@ class LIBARDOUR_API MidiSource : virtual public Source
 	virtual ~MidiSource ();
 
 	/** Write the data in the given time range to another MidiSource
-	 * \param newsrc MidiSource to which data will be written. Should be a
+	 * @param lock Reference to the Mutex to lock before modification
+	 * @param newsrc MidiSource to which data will be written. Should be a
 	 *        new, empty source. If it already has contents, the results are
 	 *        undefined. Source must be writable.
-	 * \param begin time of earliest event that can be written.
-	 * \param end time of latest event that can be written.
-	 * \return zero on success, non-zero if the write failed for any reason.
+	 * @param begin time of earliest event that can be written.
+	 * @param end time of latest event that can be written.
+	 * @return zero on success, non-zero if the write failed for any reason.
 	 */
 	int write_to (const Lock&                   lock,
 	              boost::shared_ptr<MidiSource> newsrc,
@@ -69,12 +70,13 @@ class LIBARDOUR_API MidiSource : virtual public Source
 	              Temporal::Beats               end   = std::numeric_limits<Temporal::Beats>::max());
 
 	/** Export the midi data in the given time range to another MidiSource
-	 * \param newsrc MidiSource to which data will be written. Should be a
+	 * @param lock Reference to the Mutex to lock before modification
+	 * @param newsrc MidiSource to which data will be written. Should be a
 	 *        new, empty source. If it already has contents, the results are
 	 *        undefined. Source must be writable.
-	 * \param begin time of earliest event that can be written.
-	 * \param end time of latest event that can be written.
-	 * \return zero on success, non-zero if the write failed for any reason.
+	 * @param begin time of earliest event that can be written.
+	 * @param end time of latest event that can be written.
+	 * @return zero on success, non-zero if the write failed for any reason.
 	 */
 	int export_write_to (const Lock&                   lock,
 	                     boost::shared_ptr<MidiSource> newsrc,
@@ -83,13 +85,18 @@ class LIBARDOUR_API MidiSource : virtual public Source
 
 	/** Read the data in a given time range from the MIDI source.
 	 * All time stamps in parameters are in audio samples (even if the source has tempo time).
-	 * \param dst Ring buffer where read events are written.
-	 * \param source_start Start position of the SOURCE in this read context.
-	 * \param start Start of range to be read.
-	 * \param cnt Length of range to be read (in audio samples).
-	 * \param loop_range If non-null, all event times will be mapped into this loop range.
-	 * \param tracker an optional pointer to MidiStateTracker object, for note on/off tracking.
-	 * \param filtered Parameters whose MIDI messages will not be returned.
+	 * @param lock Reference to the Mutex to lock before modification
+	 * @param dst Ring buffer where read events are written.
+	 * @param source_start Start position of the SOURCE in this read context.
+	 * @param start Start of range to be read.
+	 * @param cnt Length of range to be read (in audio samples).
+	 * @param loop_range If non-null, all event times will be mapped into this loop range.
+	 * @param cursor Cached iterator to start copying events
+	 * @param filter Channel filter to apply or NULL to disable filter
+	 * @param tracker an optional pointer to MidiStateTracker object, for note on/off tracking.
+	 * @param filtered Parameters whose MIDI messages will not be returned.
+	 * @param pos_beats Start position (quarter note = \p pos_beats - \p start_beats)
+	 * @param start_beats Start position offset
 	 */
 	virtual samplecnt_t midi_read (const Lock&                        lock,
 	                              Evoral::EventSink<samplepos_t>&     dst,
@@ -101,16 +108,17 @@ class LIBARDOUR_API MidiSource : virtual public Source
 	                              MidiStateTracker*                  tracker,
 	                              MidiChannelFilter*                 filter,
 	                              const std::set<Evoral::Parameter>& filtered,
-	                              const double                       pulse,
+	                              const double                       pos_beats,
 	                              const double                       start_beats) const;
 
 	/** Write data from a MidiRingBuffer to this source.
-	 *  @param source Source to read from.
-	 *  @param source_start This source's start position in session samples.
-	 *  @param cnt The length of time to write.
+	 * @param lock Reference to the Mutex to lock before modification
+	 * @param source Source to read from.
+	 * @param source_start This source's start position in session samples.
+	 * @param cnt The length of time to write.
 	 */
 	virtual samplecnt_t midi_write (const Lock&                 lock,
-	                               MidiRingBuffer<samplepos_t>& src,
+	                               MidiRingBuffer<samplepos_t>& source,
 	                               samplepos_t                  source_start,
 	                               samplecnt_t                  cnt);
 
@@ -218,9 +226,10 @@ class LIBARDOUR_API MidiSource : virtual public Source
 	                                  MidiChannelFilter*             filter) const = 0;
 
 	/** Write data to this source from a MidiRingBuffer.
-	 *  @param source Buffer to read from.
-	 *  @param position This source's start position in session samples.
-	 *  @param cnt The duration of this block to write for.
+	 * @param lock Reference to the Mutex to lock before modification
+	 * @param source Buffer to read from.
+	 * @param position This source's start position in session samples.
+	 * @param cnt The duration of this block to write for.
 	 */
 	virtual samplecnt_t write_unlocked (const Lock&                 lock,
 	                                   MidiRingBuffer<samplepos_t>& source,
diff --git a/libs/ardour/ardour/note_fixer.h b/libs/ardour/ardour/note_fixer.h
index 6a0a2d6695..3e6fea6551 100644
--- a/libs/ardour/ardour/note_fixer.h
+++ b/libs/ardour/ardour/note_fixer.h
@@ -61,9 +61,11 @@ public:
 	 * are enqueued to compensate for edits which should be later sent with
 	 * emit() at the start of the next read.
 	 *
+	 * @param tempo_map The tempo-map
 	 * @param cmd Command to compensate for.
 	 * @param origin Timeline position of edited source.
 	 * @param pos Current read position (last read end).
+	 * @param active_notes currently active notes (read/write)
 	 */
 	void prepare(TempoMap&                          tempo_map,
 	             const MidiModel::NoteDiffCommand*  cmd,
diff --git a/libs/ardour/ardour/plugin.h b/libs/ardour/ardour/plugin.h
index 9b35b75bf9..8433bf4447 100644
--- a/libs/ardour/ardour/plugin.h
+++ b/libs/ardour/ardour/plugin.h
@@ -211,7 +211,7 @@ class LIBARDOUR_API Plugin : public PBD::StatefulDestructible, public HasLatency
 
 	/** Create a new plugin-preset from the current state
 	 *
-	 * @param_name label to use for new preset (needs to be unique)
+	 * @param name label to use for new preset (needs to be unique)
 	 * @return PresetRecord with empty URI on failure
 	 */
 	PresetRecord save_preset (std::string name);
diff --git a/libs/ardour/ardour/region_factory.h b/libs/ardour/ardour/region_factory.h
index 97a5400925..a3f61f8819 100644
--- a/libs/ardour/ardour/region_factory.h
+++ b/libs/ardour/ardour/region_factory.h
@@ -62,7 +62,7 @@ public:
 	*/
 	static PBD::Signal1<void,boost::shared_ptr<Region> >  CheckNewRegion;
 
-	/** create a "pure copy" of Region @param other */
+	/** create a "pure copy" of Region \p other */
 	static boost::shared_ptr<Region> create (boost::shared_ptr<const Region> other, bool announce = false, bool fork = false);
 	static boost::shared_ptr<Region> create (boost::shared_ptr<Region> other, bool announce, bool fork) {
 		return create (boost::shared_ptr<const Region>(other), announce, fork);
@@ -75,19 +75,19 @@ public:
 	/** create a region from a multiple sources */
 	static boost::shared_ptr<Region> create (const SourceList &,
 	                                         const PBD::PropertyList&, bool announce = true);
-	/** create a copy of @other starting at zero within @param other's sources */
+	/** create a copy of \p other starting at zero within \p other's sources */
 	static boost::shared_ptr<Region> create (boost::shared_ptr<Region> other,
 	                                         const PBD::PropertyList&, bool announce = true);
-	/** create a copy of @param other starting at @param offset within @param other */
+	/** create a copy of \p other starting at \p offset within \p other */
 	static boost::shared_ptr<Region> create (boost::shared_ptr<Region> other, ARDOUR::MusicSample offset,
 	                                         const PBD::PropertyList&, bool announce = true);
-	/** create a "copy" of @param other but using a different set of sources @param srcs */
+	/** create a "copy" of \p other but using a different set of sources \p srcs */
 	static boost::shared_ptr<Region> create (boost::shared_ptr<Region> other, const SourceList& srcs,
 	                                         const PBD::PropertyList&, bool announce = true);
 
 	/** create a region with no sources, using XML state */
 	static boost::shared_ptr<Region> create (Session&, XMLNode&, bool);
-	/** create a region with specified sources @param srcs and XML state */
+	/** create a region with specified sources \p srcs and XML state */
 	static boost::shared_ptr<Region> create (SourceList& srcs, const XMLNode&);
 
 	static boost::shared_ptr<Region> get_whole_region_for_source (boost::shared_ptr<ARDOUR::Source>);
diff --git a/libs/ardour/ardour/session.h b/libs/ardour/ardour/session.h
index 00e2439f61..ea0e4008db 100644
--- a/libs/ardour/ardour/session.h
+++ b/libs/ardour/ardour/session.h
@@ -265,9 +265,11 @@ public:
 	std::string new_audio_source_path_for_embedded (const std::string& existing_path);
 	std::string new_audio_source_path (const std::string&, uint32_t nchans, uint32_t chan, bool destructive, bool take_required);
 	std::string new_midi_source_path (const std::string&, bool need_source_lock = true);
+
 	/** create a new track or bus from a template (XML path)
 	 * @param how_many how many tracks or busses to create
 	 * @param template_path path to xml template file
+	 * @param insert_at position where to add new track, use PresentationInfo::max_order to append at the end.
 	 * @param name name (prefix) of the route to create
 	 * @param pd Playlist disposition
 	 * @return list of newly created routes
@@ -539,6 +541,8 @@ public:
 	 * @param pending save a 'recovery', not full state (default: false)
 	 * @param switch_to_snapshot switch to given snapshot after saving (default: false)
 	 * @param template_only save a session template (default: false)
+	 * @param for_archive save only data relevant for session-archive
+	 * @param only_used_assets skip Sources that are not used, mainly useful with \p for_archive
 	 * @return zero on success
 	 */
 	int save_state (std::string snapshot_name,
diff --git a/libs/ardour/ardour/transport_master.h b/libs/ardour/ardour/transport_master.h
index 98c4f11156..cfeb2f894a 100644
--- a/libs/ardour/ardour/transport_master.h
+++ b/libs/ardour/ardour/transport_master.h
@@ -209,9 +209,12 @@ class LIBARDOUR_API TransportMaster : public PBD::Stateful {
 	 *
 	 * @param speed - The transport speed requested
 	 * @param position - The transport position requested
+	 * @param lp last position (used for flywheel)
+	 * @param when last timestamp (used for flywheel)
+	 * @param now monotonic sample time
 	 * @return - The return value is currently ignored (see Session::follow_slave)
 	 */
-	virtual bool speed_and_position (double& speed, samplepos_t& position, samplepos_t & lp, samplepos_t & when, samplepos_t now);
+	virtual bool speed_and_position (double& speed, samplepos_t& position, samplepos_t& lp, samplepos_t& when, samplepos_t now);
 
 	virtual void reset (bool with_position) = 0;
 
diff --git a/libs/canvas/canvas/canvas.h b/libs/canvas/canvas/canvas.h
index b7060e60c0..7733f07a95 100644
--- a/libs/canvas/canvas/canvas.h
+++ b/libs/canvas/canvas/canvas.h
@@ -135,7 +135,7 @@ public:
 	virtual Coord height () const = 0;
 
 	/** Store the coordinates of the mouse pointer in window coordinates in
-	 * @param winpos. Return true if the position was within the window,
+	 * \p winpos . Return true if the position was within the window,
 	 * false otherwise.
 	 */
 	virtual bool get_mouse_position (Duple& winpos) const = 0;
@@ -147,9 +147,9 @@ public:
 
 	sigc::signal<void> PreRender;
 
-	/** Ensures that the position given by @param winpos (in window
+	/** Ensures that the position given by \p winpos (in window
 	 * coordinates) is within the current window area, possibly reduced by
-	 * @param border.
+	 * \p border.
 	 */
 	Duple clamp_to_window (Duple const& winpos, Duple border = Duple());
 
diff --git a/libs/canvas/canvas/interpolated_curve.h b/libs/canvas/canvas/interpolated_curve.h
index 2faf70dde6..3a8706a6bf 100644
--- a/libs/canvas/canvas/interpolated_curve.h
+++ b/libs/canvas/canvas/interpolated_curve.h
@@ -36,7 +36,7 @@ protected:
 
 	/**
 	 * This method will calculate the Catmull-Rom interpolation curve, returning
-	 * it as a list of Coord coordinate objects.  This method in particular
+	 * it as a list of Coord coordinate objects. This method in particular
 	 * adds the first and last control points which are not visible, but required
 	 * for calculating the spline.
 	 *
@@ -47,6 +47,8 @@ protected:
 	 * point will depend on the spacing between the control points.
 	 * @return The list of interpolated coordinates.
 	 * @param curve_type Chordal (stiff), Uniform(floppy), or Centripetal(medium)
+	 * @param closed Specify if the shape is open or closed
+	 * @param results List of calculated coordinates
 	 * @throws gov.ca.water.shapelite.analysis.CatmullRomException if
 	 * points_per_segment is less than 2.
 	 */
@@ -176,7 +178,7 @@ private:
 	 * or centripetal curve types. Uniform can produce loops, chordal can
 	 * produce large distortions from the original lines, and centripetal is an
 	 * optimal balance without spaces.
-	 * @return the list of coordinates that define the CatmullRom curve
+	 * @param results List of calculated coordinates that define the CatmullRom curve
 	 * between the points defined by index+1 and index+2.
 	 */
 	static void
diff --git a/libs/canvas/canvas/item.h b/libs/canvas/canvas/item.h
index e71419e30c..d9d644abe1 100644
--- a/libs/canvas/canvas/item.h
+++ b/libs/canvas/canvas/item.h
@@ -83,22 +83,23 @@ public:
 	 */
 	virtual void prepare_for_render (Rect const & area) const { }
 
-	/** Adds one or more items to the vector @param items based on their
-	 * covering @param point which is in **window** coordinates
+	/** Adds one or more items to the vector \p items based on their
+	 * covering \p point which is in window coordinates
 	 *
 	 * Note that Item::add_items_at_window_point() is only intended to be
 	 * called on items already looked up in a LookupTable (i.e. by a
-	 * parent) and thus known to cover @param point already.
+	 * parent) and thus known to cover \p point already.
 	 *
 	 * Derived classes may add more items than themselves (e.g. containers).
 	 */
-	virtual void add_items_at_point (Duple /*point*/, std::vector<Item const *>& items) const;
+	virtual void add_items_at_point (Duple point, std::vector<Item const *>& items) const;
 
-	/** Return true if the item covers @param point, false otherwise.
+	/** Test if point is inside the item
 	 *
-	 * The point is in window coordinates
+	 * @param point The point is in window coordinates
+	 * @return true if the item covers \p point , false otherwise.
 	 */
-	virtual bool covers (Duple const &) const;
+	virtual bool covers (Duple const& point) const;
 
 	/** Update _bounding_box and _bounding_box_dirty */
 	virtual void compute_bounding_box () const = 0;
@@ -118,13 +119,14 @@ public:
 	const Item* closest_ancestor_with (const Item& other) const;
 	bool common_ancestor_within (uint32_t, const Item& other) const;
 
-	/** returns true if this item is an ancestor of @param candidate,
+	/** returns true if this item is an ancestor of \p candidate ,
 	 * and false otherwise.
 	 */
 	bool is_ancestor_of (const Item& candidate) const {
 		return candidate.is_descendant_of (*this);
 	}
-	/** returns true if this Item is a descendant of @param candidate,
+
+	/** returns true if this Item is a descendant of \p candidate ,
 	 * and false otherwise.
 	 */
 	bool is_descendant_of (const Item& candidate) const;
diff --git a/libs/temporal/temporal/time.h b/libs/temporal/temporal/time.h
index d75c232fe9..e527965d99 100644
--- a/libs/temporal/temporal/time.h
+++ b/libs/temporal/temporal/time.h
@@ -120,26 +120,46 @@ timecode_format_sampletime (
     double  sample_sample_rate,
     double timecode_frames_per_second, bool timecode_drop_frames);
 
+/** Convert timecode (frames per second) to audio sample time (samples per second)
+ *
+ * @param timecode Timecode to convert (also includes frame-rate)
+ * @param sample returned corresponding audio sample time
+ * @param use_offset apply offset as given by \p offset_is_negative and \p offset_samples
+ * @param use_subframes use \p subframes_per_frame when converting
+ * @param sample_sample_rate target sample-rate, may include pull up/down
+ * @param subframes_per_frame sub-frames per frame -- must not be 0 if \p use_subframes \c == \c true
+ * @param offset_is_negative true if offset_samples is to be subtracted
+ * @param offset_samples sample offset to add or subtract
+ */
 void LIBTEMPORAL_API
 timecode_to_sample (
-    Timecode::Time& timecode, int64_t& sample,
+    Timecode::Time const& timecode, int64_t& sample,
     bool use_offset, bool use_subframes,
-    /* Note - framerate info is taken from Timecode::Time& */
-    double   sample_sample_rate /**< may include pull up/down */,
-    uint32_t subframes_per_frame /**< must not be 0 if use_subframes==true */,
-    /* optional offset  - can be improved: function pointer to lazily query this*/
+    double   sample_sample_rate,
+    uint32_t subframes_per_frame,
     bool offset_is_negative, int64_t offset_samples);
 
+/** Convert audio sample time (samples per second) to timecode (frames per second)
+ *
+ * @param sample audio sample time to convert
+ * @param timecode resulting Timecode
+ * @param use_offset apply offset as given by \p offset_is_negative and \p offset_samples
+ * @param use_subframes use \p subframes_per_frame when converting
+ * @param timecode_frames_per_second target framerate
+ * @param timecode_drop_frames true if fps uses drop-frame-counting. only valid for \c 29.97 \c = \c 30000/1001 fps
+ * @param sample_sample_rate source sample-rate, may include pull up/down
+ * @param subframes_per_frame sub-frames per frame -- must not be 0 if \p use_subframes \c == \c true
+ * @param offset_is_negative true if offset_samples is to be subtracted
+ * @param offset_samples sample offset to add or subtract
+ */
 void LIBTEMPORAL_API
 sample_to_timecode (
     int64_t sample, Timecode::Time& timecode,
     bool use_offset, bool use_subframes,
-    /* framerate info */
     double   timecode_frames_per_second,
     bool     timecode_drop_frames,
-    double   sample_sample_rate /**< can include pull up/down */,
+    double   sample_sample_rate,
     uint32_t subframes_per_frame,
-    /* optional offset  - can be improved: function pointer to lazily query this*/
     bool offset_is_negative, int64_t offset_samples);
 
 } // namespace Timecode
diff --git a/libs/temporal/time.cc b/libs/temporal/time.cc
index c2bf96141f..5de23f342d 100644
--- a/libs/temporal/time.cc
+++ b/libs/temporal/time.cc
@@ -644,7 +644,7 @@ bool parse_timecode_format(std::string tc, Timecode::Time &TC) {
 
 void
 timecode_to_sample(
-	Timecode::Time& timecode, int64_t& sample,
+	Timecode::Time const& timecode, int64_t& sample,
 	bool use_offset, bool use_subframes,
 	/* Note - framerate info is taken from Timecode::Time& */
 	double sample_sample_rate /**< may include pull up/down */,
diff --git a/libs/waveview/waveview/wave_view.h b/libs/waveview/waveview/wave_view.h
index 5dbb2909ab..6a8012b5e4 100644
--- a/libs/waveview/waveview/wave_view.h
+++ b/libs/waveview/waveview/wave_view.h
@@ -87,8 +87,8 @@ public:
 	void set_channel (int);
 	void set_region_start (ARDOUR::sampleoffset_t);
 
-	/** Change the first position drawn by @param pixels.
-	 * @param pixels must be positive. This is used by
+	/** Change the first position drawn by \p pixels .
+	 * \p pixels must be positive. This is used by
 	 * AudioRegionViews in Ardour to avoid drawing the
 	 * first pixel of a waveform, and exists in case
 	 * there are uses for WaveView where we do not