Fix remaining doxygen warnings (!)

10 files changed, 53 insertions, 33 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;