Fix a few hundred doxygen warnings..

There are still over a hundred left, but this addresses many already.
In particular @param references to undocumented parameters.
Most notably in audio_backend.h

11 files changed, 334 insertions, 204 deletions

diff --git a/libs/ardour/ardour/audio_backend.h b/libs/ardour/ardour/audio_backend.h
index a6e42bf570..60d6ed124e 100644
--- a/libs/ardour/ardour/audio_backend.h
+++ b/libs/ardour/ardour/audio_backend.h
@@ -175,13 +175,13 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      */
     virtual std::vector<std::string> enumerate_drivers() const { return std::vector<std::string>(); }
 
-    /** Returns zero if the backend can successfully use @param name as the
-     * driver, non-zero otherwise.
+    /** Returns zero if the backend can successfully use \param drivername
+		 * as the driver, non-zero otherwise.
      *
      * Should not be used unless the backend returns true from
      * requires_driver_selection()
      */
-    virtual int set_driver (const std::string& /*drivername*/) { return 0; }
+    virtual int set_driver (const std::string& drivername) { return 0; }
 
     /** used to list device names along with whether or not they are currently
      *  available.
@@ -288,7 +288,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
 	virtual bool get_use_buffered_io () { return false; }
 
     /** Returns a collection of float identifying sample rates that are
-     * potentially usable with the hardware identified by @param device.
+     * potentially usable with the hardware identified by \param device .
      * Any of these values may be supplied in other calls to this backend
      * as the desired sample rate to use with the name device, but the
      * requested sample rate may turn out to be unavailable, or become invalid
@@ -296,7 +296,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      */
     virtual std::vector<float> available_sample_rates (const std::string& device) const = 0;
 
-    /* backends that support separate input and output devices should
+    /* backends that suppor586t separate input and output devices should
      * implement this function and return an intersection (not union) of available
      * sample rates valid for the given input + output device combination.
      */
@@ -321,7 +321,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
     }
 
     /** Returns a collection of uint32 identifying buffer sizes that are
-     * potentially usable with the hardware identified by @param device.
+     * potentially usable with the hardware identified by \param device .
      * Any of these values may be supplied in other calls to this backend
      * as the desired buffer size to use with the name device, but the
      * requested buffer size may turn out to be unavailable, or become invalid
@@ -353,7 +353,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
     }
 
     /** Returns the maximum number of input channels that are potentially
-     * usable with the hardware identified by @param device.  Any number from 1
+     * usable with the hardware identified by \param device . Any number from 1
      * to the value returned may be supplied in other calls to this backend as
      * the input channel count to use with the name device, but the requested
      * count may turn out to be unavailable, or become invalid at any time.
@@ -361,7 +361,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
     virtual uint32_t available_input_channel_count (const std::string& device) const = 0;
 
     /** Returns the maximum number of output channels that are potentially
-     * usable with the hardware identified by @param device.  Any number from 1
+     * usable with the hardware identified by \param device . Any number from 1
      * to the value returned may be supplied in other calls to this backend as
      * the output channel count to use with the name device, but the requested
      * count may turn out to be unavailable, or become invalid at any time.
@@ -429,7 +429,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      */
     virtual int set_buffer_size (uint32_t) = 0;
     /** Set the preferred underlying hardware data layout.
-     * If @param yn is true, then the hardware will interleave
+     * If \param yn is true, then the hardware will interleave
      * samples for successive channels; otherwise, the hardware will store
      * samples for a single channel contiguously.
      *
@@ -506,7 +506,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      */
     virtual std::vector<std::string> enumerate_midi_options () const = 0;
 
-    /* Request the use of the MIDI option named @param option, which
+    /* Request the use of the MIDI option named \param option, which
      * should be one of the strings returned by enumerate_midi_options()
      *
      * @return zero if successful, non-zero otherwise
@@ -534,8 +534,8 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      * the most recent calls to set_sample_rate() etc. etc.
      *
      * At some undetermined time after this function is successfully called,
-     * the backend will start calling the ::process_callback() method of
-     * the AudioEngine referenced by @param engine. These calls will
+     * the backend will start calling the process_callback method of
+     * the AudioEngine referenced by \ref engine. These calls will
      * occur in a thread created by and/or under the control of the backend.
      *
      * @param for_latency_measurement if true, the device is being started
@@ -546,9 +546,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      * Return zero if successful, negative values otherwise.
      *
      *
-     *
-     *
-     * Why is this non-virtual but ::_start() is virtual ?
+     * Why is this non-virtual but \ref _start() is virtual ?
      * Virtual methods with default parameters create possible ambiguity
      * because a derived class may implement the same method with a different
      * type or value of default parameter.
@@ -566,7 +564,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
     /** Stop using the device currently in use.
      *
      * If the function is successfully called, no subsequent calls to the
-     * process_callback() of @param engine will be made after the function
+     * process_callback() of \ref engine will be made after the function
      * returns, until parameters are reset and start() are called again.
      *
      * The backend is considered to be un-configured after a successful
@@ -586,7 +584,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
 	virtual int reset_device() = 0;
 
     /** While remaining connected to the device, and without changing its
-     * configuration, start (or stop) calling the process_callback() of @param engine
+     * configuration, start (or stop) calling the process_callback of the engine
      * without waiting for the device. Once process_callback() has returned, it
      * will be called again immediately, thus allowing for faster-than-realtime
      * processing.
@@ -595,11 +593,12 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      * unaltered. However, any physical ports should NOT be used by the
      * process_callback() during freewheeling - the data behaviour is undefined.
      *
-     * If @param start_stop is true, begin this behaviour; otherwise cease this
+     * If \param start_stop is true, begin this behaviour; otherwise cease this
      * behaviour if it currently occuring, and return to calling
-     * process_callback() of @param engine by waiting for the device.
+     * process_callback() of the engine by waiting for the device.
      *
-     * Return zero on success, non-zero otherwise.
+		 * @param start_stop true to engage freewheel processing
+     * @return zero on success, non-zero otherwise.
      */
     virtual int freewheel (bool start_stop) = 0;
 
@@ -613,11 +612,11 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      * Implementations can feel free to smooth the values returned over
      * time (e.g. high pass filtering, or its equivalent).
      */
-    virtual float dsp_load() const  = 0;
+    virtual float dsp_load() const = 0;
 
     /* Transport Control (JACK is the only audio API that currently offers
-       the concept of shared transport control)
-    */
+     * the concept of shared transport control)
+     */
 
     /** Attempt to change the transport state to TransportRolling.
      */
@@ -628,15 +627,15 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
     /** return the current transport state
      */
     virtual TransportState transport_state () const { return TransportStopped; }
-    /** Attempt to locate the transport to @param pos
+    /** Attempt to locate the transport to \param pos
      */
-    virtual void transport_locate (samplepos_t /*pos*/) {}
+    virtual void transport_locate (samplepos_t pos) {}
     /** Return the current transport location, in samples measured
      * from the origin (defined by the transport time master)
      */
     virtual samplepos_t transport_sample() const { return 0; }
 
-    /** If @param yn is true, become the time master for any inter-application transport
+    /** If \param yn is true, become the time master for any inter-application transport
      * timebase, otherwise cease to be the time master for the same.
      *
      * Return zero on success, non-zero otherwise
@@ -644,7 +643,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      * JACK is the only currently known audio API with the concept of a shared
      * transport timebase.
      */
-    virtual int set_time_master (bool /*yn*/) { return 0; }
+    virtual int set_time_master (bool yn) { return 0; }
 
     virtual int        usecs_per_cycle () const { return 1000000 * (buffer_size() / sample_rate()); }
     virtual size_t     raw_buffer_size (DataType t) = 0;
@@ -680,11 +679,11 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
     /** Return true if it possible to determine the offset in samples of the
      * first video frame that starts within the current buffer process cycle,
      * measured from the first sample of the cycle. If returning true,
-     * set @param offset to that offset.
+     * set \param offset to that offset.
      *
      * Eg. if it can be determined that the first video frame within the cycle
      * starts 28 samples after the first sample of the cycle, then this method
-     * should return true and set @param offset to 28.
+     * should return true and set \param offset to 28.
      *
      * May be impossible to support outside of JACK, which has specific support
      * (in some cases, hardware support) for this feature.
@@ -692,13 +691,15 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
      * Can ONLY be called from within a process() callback tree (which implies
      * that it can only be called by a process thread)
      */
-    virtual bool get_sync_offset (pframes_t& /*offset*/) const { return false; }
+    virtual bool get_sync_offset (pframes_t& offset) const { return false; }
 
     /** Create a new thread suitable for running part of the buffer process
-     * cycle (i.e. Realtime scheduling, memory allocation, etc. etc are all
-     * correctly setup), with a stack size given in bytes by specified @param
-     * stacksize. The thread will begin executing @param func, and will exit
+     * cycle (i.e. Realtime scheduling, memory allocation, stacksize, etc.
+		 * are all correctly setup).
+		 * The thread will begin executing func, and will exit
      * when that function returns.
+		 *
+		 * @param func process function to run
      */
     virtual int create_process_thread (boost::function<void()> func) = 0;
 
@@ -722,7 +723,7 @@ class LIBARDOUR_API AudioBackend : public PortEngine {
 
     virtual void update_latencies () = 0;
 
-    /** Set @param speed and @param position to the current speed and position
+    /** Set \param speed and \param position to the current speed and position
      * indicated by some transport sync signal.  Return whether the current
      * transport state is pending, or finalized.
      *
diff --git a/libs/ardour/ardour/audio_buffer.h b/libs/ardour/ardour/audio_buffer.h
index 8fe23a034b..7d41777de4 100644
--- a/libs/ardour/ardour/audio_buffer.h
+++ b/libs/ardour/ardour/audio_buffer.h
@@ -38,7 +38,7 @@ public:
 
 	/** silence buffer
 	 * @param len number of samples to clear
-	 * @laram offset start offset
+	 * @param offset start offset
 	 */
 	void silence (samplecnt_t len, samplecnt_t offset = 0);
 
@@ -86,7 +86,7 @@ public:
 		_written = true;
 	}
 
-	/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @a dst_offset */
+	/** Accumulate (add) \param len samples from \param src starting at \param src_offset into self starting at \param dst_offset */
 	void merge_from (const Buffer& src, samplecnt_t len, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
 	{
 		const AudioBuffer* ab = dynamic_cast<const AudioBuffer*> (&src);
@@ -94,7 +94,7 @@ public:
 		accumulate_from (*ab, len, dst_offset, src_offset);
 	}
 
-	/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @a dst_offset */
+	/** Accumulate (add) \param len samples from \param src starting at \param src_offset into self starting at \param dst_offset */
 	void accumulate_from (const AudioBuffer& src, samplecnt_t len, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
 	{
 		assert (_capacity > 0);
@@ -111,7 +111,9 @@ public:
 		_written = true;
 	}
 
-	/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @a dst_offset */
+	/** Accumulate (add) \param len samples of \param src starting at \param src_offset into self
+	 * starting at \param dst_offset
+	 */
 	void accumulate_from (const Sample* src, samplecnt_t len, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
 	{
 		assert (_capacity > 0);
@@ -126,8 +128,9 @@ public:
 		_written = true;
 	}
 
-	/** Accumulate (add) @a len samples @a src starting at @a src_offset into self starting at @dst_offset
-	 * scaling by @a gain_coeff */
+	/** Accumulate (add) \param len samples if \param src starting at \param src_offset into self
+	 * starting at \param dst_offset scaling by \param gain_coeff
+	 */
 	void accumulate_with_gain_from (const AudioBuffer& src, samplecnt_t len, gain_t gain_coeff, sampleoffset_t dst_offset = 0, sampleoffset_t src_offset = 0)
 	{
 		assert (_capacity > 0);
@@ -146,8 +149,9 @@ public:
 		_written = true;
 	}
 
-	/** Accumulate (add) @a len samples FROM THE START OF @a src into self
-	 * scaling by @a gain_coeff */
+	/** Accumulate (add) \param len samples from the start of \param src_raw into self at \param dst_offset
+	 * scaling by \param gain_coeff
+	 */
 	void accumulate_with_gain_from (const Sample* src_raw, samplecnt_t len, gain_t gain_coeff, sampleoffset_t dst_offset = 0)
 	{
 		assert (_capacity > 0);
@@ -161,8 +165,9 @@ public:
 		_written = true;
 	}
 
-	/** Accumulate (add) @a len samples FROM THE START OF @a src into self
-	 * scaling by @a gain_coeff */
+	/** Accumulate (add) \param len samples from the start of \param src into self at \param dst_offset
+	 * using a linear gain ramp from \param initial to \param target .
+	 */
 	void accumulate_with_ramped_gain_from (const Sample* src, samplecnt_t len, gain_t initial, gain_t target, sampleoffset_t dst_offset = 0)
 	{
 		assert (_capacity > 0);
@@ -184,7 +189,8 @@ public:
 		_written = true;
 	}
 
-	/** apply a fixed gain factor to the audio buffer
+	/** Apply a fixed gain factor to the audio buffer
+	 *
 	 * @param gain gain factor
 	 * @param len number of samples to amplify
 	 */
@@ -213,7 +219,7 @@ public:
 		_written  = false;
 	}
 
-	/** Reallocate the buffer used internally to handle at least @nframes of data
+	/** Reallocate the buffer used internally to handle at least \param nframes of data
 	 *
 	 * Constructor MUST have been passed capacity!=0 or this will die (to prevent mem leaks).
 	 */
@@ -232,7 +238,8 @@ public:
 		return _data + offset;
 	}
 
-	/** check buffer for silence
+	/** Check buffer for silence
+	 *
 	 * @param nframes  number of samples to check
 	 * @param n first non zero sample (if any)
 	 * @return true if all samples are zero
diff --git a/libs/ardour/ardour/chan_count.h b/libs/ardour/ardour/chan_count.h
index 7819f70612..a62d5dc70f 100644
--- a/libs/ardour/ardour/chan_count.h
+++ b/libs/ardour/ardour/chan_count.h
@@ -58,12 +58,13 @@ public:
 	}
 
 	/** set channel count for given type
-	 * @param type data type
+	 * @param t data type
 	 * @param count number of channels
 	 */
 	void     set(DataType t, uint32_t count) { assert(t != DataType::NIL); _counts[t] = count; }
+
 	/** query channel count for given type
-	 * @param type data type
+	 * @param t data type
 	 * @returns channel count for given type
 	 */
 	uint32_t get(DataType t) const { assert(t != DataType::NIL); return _counts[t]; }
@@ -74,6 +75,7 @@ public:
 	 * @returns number of audio channels
 	 */
 	inline uint32_t n_audio() const { return _counts[DataType::AUDIO]; }
+
 	/** set number of audio channels
 	 * @param a number of audio channels
 	 */
@@ -83,6 +85,7 @@ public:
 	 * @returns number of midi channels
 	 */
 	inline uint32_t n_midi()  const { return _counts[DataType::MIDI]; }
+
 	/** set number of audio channels
 	 * @param m number of midi channels
 	 */
diff --git a/libs/ardour/ardour/chan_mapping.h b/libs/ardour/ardour/chan_mapping.h
index eb92329154..e73c009b58 100644
--- a/libs/ardour/ardour/chan_mapping.h
+++ b/libs/ardour/ardour/chan_mapping.h
@@ -53,29 +53,30 @@ public:
 	 * @param valid pointer to a boolean. If not NULL it is set to true if the mapping is found, and false otherwise.
 	 * @returns first "from" that matches given "to"
 	 */
-	uint32_t get_src(DataType t, uint32_t to, bool* valid) const;
+	uint32_t get_src(DataType type, uint32_t to, bool* valid) const;
 
 	/** get buffer mapping for given data type and pin
 	 * @param type data type
 	 * @param from numeric source id
 	 * @returns mapped buffer number (or ChanMapping::Invalid)
 	 */
-	uint32_t get (DataType t, uint32_t from) const { return get (t, from, NULL); }
+	uint32_t get (DataType type, uint32_t from) const { return get (type, from, NULL); }
 
 	/** set buffer mapping for given data type
 	 * @param type data type
 	 * @param from numeric source id
 	 * @param to buffer
 	 */
-	void     set(DataType t, uint32_t from, uint32_t to);
-	void     offset_from(DataType t, int32_t delta);
-	void     offset_to(DataType t, int32_t delta);
+	void     set (DataType type, uint32_t from, uint32_t to);
+
+	void     offset_from (DataType t, int32_t delta);
+	void     offset_to (DataType t, int32_t delta);
 
 	/** remove mapping
 	 * @param type data type
 	 * @param from numeric source to remove from mapping
 	 */
-	void     unset(DataType t, uint32_t from);
+	void     unset(DataType type, uint32_t from);
 
 	/** Test mapping matrix for identity
 	 * @param offset per data-type offset to take into account
diff --git a/libs/ardour/ardour/lv2_extensions.h b/libs/ardour/ardour/lv2_extensions.h
index 13ceac4cbd..26223c3d33 100644
--- a/libs/ardour/ardour/lv2_extensions.h
+++ b/libs/ardour/ardour/lv2_extensions.h
@@ -20,7 +20,7 @@
 #include "lv2/lv2plug.in/ns/lv2core/lv2.h"
 
 /**
-   @defgroup inlinedisplay Inline-Display
+   @defgroup lv2inlinedisplay Inline-Display
 
    Support for displaying a miniaturized generic view
 	 directly in the host's Mixer Window.
@@ -80,7 +80,7 @@ typedef struct {
 */
 
 /**
-   @defgroup automate Self-Automation
+   @defgroup lv2automate Self-Automation
 
    Support for plugins to write automation data via Atom Events
 
@@ -111,7 +111,7 @@ typedef struct {
 */
 
 /**
-   @defgroup license License-Report
+   @defgroup lv2license License-Report
 
    Allow for commercial LV2 to report their
 	 licensing status.
@@ -149,7 +149,7 @@ typedef struct _LV2_License_Interface {
 */
 
 /**
-   @defgroup plugin provided bypass
+   @defgroup lv2bypass Plugin-provided bypass
 
 	 A port with the designation "processing#enable" must
 	 control a plugin's internal bypass mode.
@@ -182,7 +182,7 @@ typedef struct _LV2_License_Interface {
 
 
 /**
-   @defgroup plugin port/routing control
+   @defgroup lv2routing plugin port/routing control
 
    This is a "feature" to simplify per port meta-data of
    http://lv2plug.in/ns/ext/port-groups/port-groups.html#source
@@ -204,7 +204,7 @@ typedef struct _LV2_License_Interface {
 */
 
 /**
-   @defgroup midnam MIDI Naming
+   @defgroup lv2midnam MIDI Naming
 
    @{
 */
@@ -231,7 +231,7 @@ typedef struct {
 	 * text which is a valid midnam desciption
 	 * (or NULL in case of error).
 	 *
-	 * The midnam <Model> must be unique and
+	 * The midnam \<Model\> must be unique and
 	 * specific for the given plugin-instance.
 	 */
 	char* (*midnam)(LV2_Handle instance);
@@ -253,7 +253,10 @@ typedef struct {
 */
 
 /**
-   @defgroup bankpatch
+   @defgroup lv2bankpatch MIDI Bank/Patch Notifications
+
+	 LV2 extension to allow a synth to inform a host about the
+	 currentl used MIDI bank/program.
 
    @{
 */
diff --git a/libs/ardour/ardour/port_engine.h b/libs/ardour/ardour/port_engine.h
index 6f6cdf0106..71f31cb3c3 100644
--- a/libs/ardour/ardour/port_engine.h
+++ b/libs/ardour/ardour/port_engine.h
@@ -86,14 +86,15 @@ public:
 	 */
 	virtual void* private_handle() const = 0;
 
-	/* We use void* here so that the API can be defined for any implementation.
+	/** Opaque handle to use as reference for Ports
 	 *
-	 * We could theoretically use a template (PortEngine<T>) and define
+	 * We use void* here so that the API can be defined for any implementation.
+	 *
+	 * We could theoretically use a template (PortEngine\<T\>) and define
 	 * PortHandle as T, but this complicates the desired inheritance
 	 * pattern in which FooPortEngine handles things for the Foo API,
-	 * rather than being a derivative of PortEngine<Foo>.
+	 * rather than being a derivative of PortEngine\<Foo\>.
 	 */
-
 	typedef void* PortHandle;
 
 	/** Return the name of this process as used by the port manager
@@ -101,23 +102,32 @@ public:
 	 */
 	virtual const std::string& my_name() const = 0;
 
-	/** Return the maximum size of a port name
-	*/
+	/** Return the maximum size of a port name */
 	virtual uint32_t port_name_size() const = 0;
 
-	/** Returns zero if the port referred to by @param port was set to @param
-	 * name. Return non-zero otherwise.
+	/** Set/rename port
+	 *
+	 * @param port \ref PortHandle to operate on
+	 * @param name new name to use for this port
+	 * @return zero if successful, non-zero otherwise
 	 */
 	virtual int         set_port_name (PortHandle port, const std::string& name) = 0;
-	/** Return the name of the port referred to by @param port. If the port
-	 * does not exist, return an empty string.
+
+	/** Query port name
+	 *
+	 * @param port \ref PortHandle
+	 * @return the name of the port referred to by @param port . If the port
+	 *         does not exist, return an empty string.
 	 */
-	virtual std::string get_port_name (PortHandle) const = 0;
+	virtual std::string get_port_name (PortHandle port) const = 0;
 
-	/** Return the flags of the port referred to by @param port. If the port
-	 * does not exist, return PortFlags (0)
+	/** Query port-flags
+	 *
+	 * @param port \ref PortHandle
+	 * @return the flags of the port referred to by \param port . If the port
+	 *         does not exist, return PortFlags (0)
 	 */
-	virtual PortFlags get_port_flags (PortHandle) const = 0;
+	virtual PortFlags get_port_flags (PortHandle port) const = 0;
 
 	/** Return the port-property value and type for a given key.
 	 * (eg query a human readable port name)
@@ -149,132 +159,194 @@ public:
 	 */
 	virtual int set_port_property (PortHandle, const std::string& key, const std::string& value, const std::string& type) { return -1; }
 
-	/** Return a reference to a port with the fullname @param name. Return
-	 * an "empty" PortHandle (analogous to a null pointer) if no such port exists.
+	/** Return a reference to a port with the fullname \param name .
+	 *
+	 * @param name Full port-name to lookup
+	 * @return PortHandle if lookup was successful, or an "empty" PortHandle (analogous to a null pointer) if no such port exists.
 	 */
-	virtual PortHandle get_port_by_name (const std::string&) const = 0;
+	virtual PortHandle get_port_by_name (const std::string& name) const = 0;
 
 	/** Find the set of ports whose names, types and flags match
-	 * specified values, place the names of each port into @param ports,
-	 * and return the count of the number found.
-	 *
-	 * To avoid selecting by name, pass an empty string for @param
-	 * port_name_pattern.
+	 * specified values, place the names of each port into \param ports .
 	 *
-	 * To avoid selecting by type, pass DataType::NIL as @param type.
-	 *
-	 * To avoid selecting by flags, pass PortFlags (0) as @param flags.
+	 * @param port_name_pattern match by given pattern. To avoid selecting by name, pass an empty string.
+	 * @param type filter by given type; pass DataType::NIL to match all types.
+	 * @param flags filter by flags, pass PortFlags (0) to avoid selecting by flags.
+	 * @return the count of the number found
 	 */
 	virtual int get_ports (const std::string& port_name_pattern, DataType type, PortFlags flags, std::vector<std::string>& ports) const = 0;
 
-	/** Return the Ardour data type handled by the port referred to by @param
-	 * port. Returns DataType::NIL if the port does not exist.
+	/** Lookup data type of a port
+	 *
+	 * @param port \ref PortHandle of the port to lookup.
+	 * @return the Ardour data type handled by the port referred to by \param port .
+	 *         DataType::NIL is returned if the port does not exist.
 	 */
 	virtual DataType port_data_type (PortHandle port) const = 0;
 
-	/** Create a new port whose fullname will be the conjuction of my_name(),
-	 * ":" and @param shortname. The port will handle data specified by @param
-	 * type and will have the flags given by @param flags. If successfull,
-	 * return a reference to the port, otherwise return a null pointer.
+	/** Create a new port whose fullname will be the conjunction of my_name(),
+	 * ":" and \param shortname . The port will handle data specified by \param type
+	 * and will have the flags given by \param flags . If successful,
+	 *
+	 * @param shortname Name of port to create
+	 * @param type type of port to create
+	 * @param flags flags of the port to create
+	 * @return a reference to the port, otherwise return a null pointer.
 	 */
 	virtual PortHandle register_port (const std::string& shortname, ARDOUR::DataType type, ARDOUR::PortFlags flags) = 0;
 
-	/* Destroy the port referred to by @param port, including all resources
-	 * associated with it. This will also disconnect @param port from any ports it
+	/* Destroy the port referred to by \param port, including all resources
+	 * associated with it. This will also disconnect \param port from any ports it
 	 * is connected to.
+	 *
+	 * @param port \ref PortHandle of the port to destroy
 	 */
-	virtual void       unregister_port (PortHandle) = 0;
+	virtual void       unregister_port (PortHandle port) = 0;
 
 	/* Connection management */
 
-	/** Ensure that data written to the port named by @param src will be
-	 * readable from the port named by @param dst. Return zero on success,
-	 * non-zero otherwise.
+	/** Ensure that data written to the port named by \param src will be
+	 * readable from the port named by \param dst
+	 *
+	 * @param src name of source port to connect
+	 * @param dst name of destination (sink) port
+	 * @return zero on success, non-zero otherwise.
 	 */
 	virtual int   connect (const std::string& src, const std::string& dst) = 0;
 
-	/** Remove any existing connection between the ports named by @param src and
-	 * @param dst. Return zero on success, non-zero otherwise.
+	/** Remove any existing connection between the ports named by \param src and
+	 * \param dst
+	 *
+	 * @param src name of source port to dis-connect to disconnect from
+	 * @param dst name of destination (sink) port to disconnect
+	 * @return zero on success, non-zero otherwise.
 	 */
 	virtual int   disconnect (const std::string& src, const std::string& dst) = 0;
 
-
-	/** Ensure that data written to the port referenced by @param portwill be
-	 * readable from the port named by @param dst. Return zero on success,
-	 * non-zero otherwise.
+	/** Ensure that data written to the port referenced by \param src will be
+	 * readable from the port named by \param dst
+	 *
+	 * @param src \ref PortHandle of source port to connect
+	 * @param dst \ref PortHandle of destination (sink) port
+	 * @return zero on success, non-zero otherwise.
 	 */
 	virtual int   connect (PortHandle src, const std::string& dst) = 0;
-	/** Remove any existing connection between the port referenced by @param src and
-	 * the port named @param dst. Return zero on success, non-zero otherwise.
+
+	/** Remove any existing connection between the port referenced by \param src and
+	 * the port named \param dst
+	 *
+	 * @param src \ref PortHandle of source port to disconnect from
+	 * @param dst \ref PortHandle of destination (sink) port to disconnect
+	 * @return zero on success, non-zero otherwise.
 	 */
 	virtual int   disconnect (PortHandle src, const std::string& dst) = 0;
 
-	/** Remove all connections between the port referred to by @param port and
-	 * any other ports. Return zero on success, non-zero otherwise.
+	/** Remove all connections between the port referred to by \param port and
+	 * any other ports.
+	 *
+	 * @param port \ref PortHandle of port to disconnect
+	 * @return zero on success, non-zero otherwise.
 	 */
 	virtual int   disconnect_all (PortHandle port) = 0;
 
-	/** Return true if the port referred to by @param port has any connections
-	 * to other ports. Return false otherwise.
+	/** Test if given \param port is connected
+	 *
+	 * @param port \ref PortHandle of port to test
+	 * @param process_callback_safe true if this method is not called from rt-context of backend callbacks
+	 * @return true if the port referred to by \param port has any connections to other ports. Return false otherwise.
 	 */
 	virtual bool  connected (PortHandle port, bool process_callback_safe = true) = 0;
-	/** Return true if the port referred to by @param port is connected to
-	 * the port named by @param name. Return false otherwise.
+
+	/** Test port connection
+	 *
+	 * @param port \ref PortHandle of source port to test
+	 * @param name name of destination to test
+	 * @param process_callback_safe true if this method is not called from rt-context of backend callbacks
+	 * @return true if the port referred to by \param port is connected to the port named by \param name . Return false otherwise.
 	 */
-	virtual bool  connected_to (PortHandle, const std::string& name, bool process_callback_safe = true) = 0;
+	virtual bool  connected_to (PortHandle port, const std::string& name, bool process_callback_safe = true) = 0;
 
-	/** Return true if the port referred to by @param port has any connections
-	 * to ports marked with the PortFlag IsPhysical. Return false otherwise.
+	/** Test if given \param port is is connected to physical I/O ports.
+	 *
+	 * @param port \ref PortHandle of source port to test
+	 * @param process_callback_safe true if this method is not called from rt-context of backend callbacks
+	 * @return true if the port referred to by \param port has any connections
+	 *         to ports marked with the PortFlag IsPhysical. Return false otherwise.
 	 */
 	virtual bool  physically_connected (PortHandle port, bool process_callback_safe = true) = 0;
 
-	/** Return true if the port referred to by @param port has any connections
-	 * to external, not-ardour owned, ports.
+	/** Test if given \param port is has external connections.
+	 *
+	 * @param port \ref PortHandle of port to test
+	 * @param process_callback_safe true if this method is not called from rt-context of backend callbacks
+	 * @return true if the port referred to by \param port has any connections
+	 *         to external, not-ardour owned, ports.
 	 */
 	virtual bool  externally_connected (PortHandle port, bool process_callback_safe = true) {
 		/* only with JACK, provides client ports that are not physical */
 		return physically_connected (port, process_callback_safe);
 	}
 
-	/** Place the names of all ports connected to the port named by @param
-	 * ports into @param names, and return the number of connections.
+	/** Place the names of all ports connected to the port named by
+	 * \param port into \param names .
+	 *
+	 * @param port \ref PortHandle
+	 * @param names array or returned port-names
+	 * @param process_callback_safe true if this method is not called from rt-context of backend callbacks
+	 * @return number of connections found
 	 */
 	virtual int   get_connections (PortHandle port, std::vector<std::string>& names, bool process_callback_safe = true) = 0;
 
 	/* MIDI */
 
-	/** Retrieve a MIDI event from the data at @param port_buffer. The event
-		number to be retrieved is given by @param event_index (a value of zero
-		indicates that the first event in the port_buffer should be retrieved).
+	/** Retrieve a MIDI event from the data at \param port_buffer . The event
+	 * number to be retrieved is given by \param event_index (a value of zero
+	 * indicates that the first event in the port_buffer should be retrieved).
 	 *
 	 * The data associated with the event will be copied into the buffer at
-	 * @param buf and the number of bytes written will be stored in @param
-	 * size. The timestamp of the event (which is always relative to the start
-	 * of the current process cycle, in samples) will be stored in @param
-	 * timestamp
+	 * \param buf and the number of bytes written will be stored in \param size .
+	 * The timestamp of the event (which is always relative to the start
+	 * of the current process cycle, in samples) will be stored in \param timestamp .
+	 *
+	 * @param timestamp time in samples relative to the current cycle start
+	 * @param size number of bytes read into \param buf
+	 * @param buf raw MIDI data
+	 * @param port_buffer the midi-port buffer
+	 * @param event_index index of event to retrieve
+	 * @return 0 on success, -1 otherwise
 	 */
 	virtual int      midi_event_get (pframes_t& timestamp, size_t& size, uint8_t const** buf, void* port_buffer, uint32_t event_index) = 0;
 
-	/** Place a MIDI event consisting of @param size bytes copied from the data
-	 * at @param buf into the port buffer referred to by @param
-	 * port_buffer. The MIDI event will be marked with a time given by @param
-	 * timestamp. Return zero on success, non-zero otherwise.
+	/** Place a MIDI event consisting of \param size bytes copied from the data
+	 * at \param buffer into the port buffer referred to by \param port_buffer .
+	 * The MIDI event will be marked with a time given by \param timestamp .
 	 *
 	 * Events  must be added monotonically to a port buffer. An attempt to
 	 * add a non-monotonic event (e.g. out-of-order) will cause this method
 	 * to return a failure status.
+	 *
+	 * @param port_buffer the midi-port buffer
+	 * @param timestamp time in samples relative to the current cycle start
+	 * @param buffer raw MIDI data to emplace
+	 * @param size number of bytes of \param buffer
+	 * @return zero on success, non-zero otherwise.
 	 */
 	virtual int      midi_event_put (void* port_buffer, pframes_t timestamp, const uint8_t* buffer, size_t size) = 0;
 
-	/** Return the number of MIDI events in the data at @param port_buffer
+	/** Query the number of MIDI events in the data at \param port_buffer
+	 *
+	 * @param port_buffer the midi-port buffer
+	 * @return the number of MIDI events in the data at \param port_buffer
 	*/
 	virtual uint32_t get_midi_event_count (void* port_buffer) = 0;
 
-	/** Clear the buffer at @param port_buffer of all MIDI events.
+	/** Clear the buffer at \param port_buffer of all MIDI events.
 	 *
 	 * After a call to this method, an immediate, subsequent call to
-	 * get_midi_event_count() with the same @param port_buffer argument must
+	 * \ref get_midi_event_count with the same \param port_buffer argument must
 	 * return zero.
+	 *
+	 * @param port_buffer the buffer to clear
 	 */
 	virtual void     midi_clear (void* port_buffer) = 0;
 
@@ -289,67 +361,101 @@ public:
 	 * APIs can offer it.
 	 */
 	virtual bool  can_monitor_input() const = 0;
+
 	/** Increment or decrement the number of requests to monitor the input
-	 * of the hardware channel represented by the port referred to by @param
-	 * port.
+	 * of the hardware channel represented by the port referred to by
+	 * \param port .
 	 *
 	 * If the number of requests rises above zero, input monitoring will
 	 * be enabled (if can_monitor_input() returns true for the implementation).
 	 *
 	 * If the number of requests falls to zero, input monitoring will be
 	 * disabled (if can_monitor_input() returns true for the implementation)
+	 *
+	 * @param port \ref PortHandle
+	 * @param yn true to enable hardware monitoring, false to disable
+	 * @return 0 on success, -1 otherwise
 	 */
 	virtual int   request_input_monitoring (PortHandle port, bool yn) = 0;
+
 	/* Force input monitoring of the hardware channel represented by the port
-	 * referred to by @param port to be on or off, depending on the true/false
-	 * status of @param yn. The request count is ignored when using this
-	 * method, so if this is called with yn set to false, input monitoring will
+	 * referred to by \param port to be on or off, depending on the true/false
+	 * status of \param yn. The request count is ignored when using this
+	 * method, so if this is called with \param yn set to false, input monitoring will
 	 * be disabled regardless of the number of requests to enable it.
+	 *
+	 * @param port \ref PortHandle
+	 * @param yn true to enable hardware monitoring, false to disable
+	 * @return 0 on success, -1 otherwise
 	 */
 	virtual int   ensure_input_monitoring (PortHandle port, bool yn) = 0;
-	/** Return true if input monitoring is enabled for the hardware channel
-	 * represented by the port referred to by @param port. Return false
-	 * otherwise.
+
+	/** Query status of hardware monitoring for given \param port
+	 *
+	 * @param port \ref PortHandle to test
+	 * @return true if input monitoring is enabled for the hardware channel
+	 *         represented by the port referred to by \param port .
+	 *         Return false otherwise.
 	 */
 	virtual bool  monitoring_input (PortHandle port) = 0;
 
 	/* Latency management */
 
-	/** Set the latency range for the port referred to by @param port to @param
-	 * r. The playback range will be set if @param for_playback is true,
+	/** Set the latency range for the port referred to by \param port to
+	 * \param r . The playback range will be set if \param for_playback is true,
 	 * otherwise the capture range will be set.
+	 *
+	 * @param port \ref PortHandle to operate on
+	 * @param for_playback When true, playback latency is set: How long will it be
+	 *                     until the signal arrives at the edge of the process graph.
+	 *                     When false the capture latency is set: ow long has it been
+	 *                     since the signal arrived at the edge of the process graph.
+	 * @param r min/max latency for given port.
 	 */
 	virtual void          set_latency_range (PortHandle port, bool for_playback, LatencyRange r) = 0;
-	/** Return the latency range for the port referred to by @param port.
+
+	/** Return the latency range for the port referred to by \param port .
 	 * The playback range will be returned if @param for_playback is true,
 	 * otherwise the capture range will be returned.
+	 *
+	 * @param port The PortHandle to query
+	 * @param for_playback When true, playback (downstream) latency is queried,
+	 *                     false for capture (upstream) latency.
 	 */
 	virtual LatencyRange  get_latency_range (PortHandle port, bool for_playback) = 0;
 
 	/* Discovering physical ports */
 
-	/** Return true if the port referred to by @param port has the IsPhysical
+	/** Return true if the port referred to by \param port has the IsPhysical
 	 * flag set. Return false otherwise.
+	 *
+	 * @param port \ref PortHandle to query
 	 */
 	virtual bool      port_is_physical (PortHandle port) const = 0;
 
-	/** Store into @param names the names of all ports with the IsOutput and
-	 * IsPhysical flag set, that handle data of type @param type.
+	/** Store into \param names the names of all ports with the IsOutput and
+	 * IsPhysical flag set, that handle data of type \param type .
 	 *
 	 * This can be used to discover outputs associated with hardware devices.
+	 *
+	 * @param type Data-type to lookup
+	 * @param names return value to populate with names
 	 */
 	virtual void      get_physical_outputs (DataType type, std::vector<std::string>& names) = 0;
+
 	/** Store into @param names the names of all ports with the IsInput and
-	 * IsPhysical flags set, that handle data of type @param type.
+	 * IsPhysical flags set, that handle data of type @param type .
 	 *
 	 * This can be used to discover inputs associated with hardware devices.
 	 */
 	virtual void      get_physical_inputs (DataType type, std::vector<std::string>& names) = 0;
-	/** Return the total count (possibly mixed between different data types)
+
+	/** @return the total count (possibly mixed between different data types)
 	 * of the number of ports with the IsPhysical and IsOutput flags set.
 	 */
 	virtual ChanCount n_physical_outputs () const = 0;
-	/** Return the total count (possibly mixed between different data types)
+
+	/** @return the total count (possibly mixed between different data types)
 	 * of the number of ports with the IsPhysical and IsInput flags set.
 	 */
 	virtual ChanCount n_physical_inputs () const = 0;
@@ -360,8 +466,12 @@ public:
 	 *
 	 * The return value is untyped because buffers containing different data
 	 * depending on the port type.
+	 *
+	 * @param port \ref PortHandle
+	 * @param off memory offset
+	 * @return pointer to raw memory area
 	 */
-	virtual void* get_buffer (PortHandle, pframes_t) = 0;
+	virtual void* get_buffer (PortHandle port, pframes_t off) = 0;
 
 	/* MIDI ports (the ones in libmidi++) need this to be able to correctly
 	 * schedule MIDI events within their buffers. It is a bit odd that we
diff --git a/libs/ardour/ardour/session.h b/libs/ardour/ardour/session.h
index c7b66c1139..00e2439f61 100644
--- a/libs/ardour/ardour/session.h
+++ b/libs/ardour/ardour/session.h
@@ -1992,7 +1992,7 @@ private:
 	static bool _disable_all_loaded_plugins;
 	static bool _bypass_all_loaded_plugins;
 
-	mutable bool have_looped; ///< Used in ::audible_sample(*)
+	mutable bool have_looped; ///< Used in \ref audible_sample
 
 	void update_route_record_state ();
 	gint _have_rec_enabled_track;
diff --git a/libs/libltc/ltc/ltc.h b/libs/libltc/ltc/ltc.h
index 1f6eaffb6d..5abbfa0607 100644
--- a/libs/libltc/ltc/ltc.h
+++ b/libs/libltc/ltc/ltc.h
@@ -430,8 +430,8 @@ int ltc_decoder_free(LTCDecoder *d);
  *
  * @param d decoder handle
  * @param buf pointer to ltcsnd_sample_t - unsigned 8 bit mono audio data
- * @param size \anchor size number of samples to parse
- * @param posinfo (optional, recommended) sample-offset in the audio-stream. It is added to \ref off_start, \ref off_end in \ref LTCFrameExt and should be monotonic (ie incremented by \ref size for every call to ltc_decoder_write)
+ * @param size size number of samples to parse
+ * @param posinfo (optional, recommended) sample-offset in the audio-stream. It is added to \ref off_start, \ref off_end in \ref LTCFrameExt and should be monotonic (ie incremented by \param size for every call to ltc_decoder_write)
  */
 void ltc_decoder_write(LTCDecoder *d,
 		ltcsnd_sample_t *buf, size_t size,
diff --git a/libs/pbd/pbd/controllable.h b/libs/pbd/pbd/controllable.h
index 9557e5624b..8473147336 100644
--- a/libs/pbd/pbd/controllable.h
+++ b/libs/pbd/pbd/controllable.h
@@ -52,6 +52,22 @@ namespace PBD {
  * Without overriding upper() and lower(), a derived class will function
  * as a control whose value can range between 0 and 1.0.
  *
+ *
+
+ * We express Controllable values in one of three ways:
+ * 1. `user' --- as presented to the user (e.g. dB, Hz, etc.)
+ * 2. `interface' --- as used in some cases for the UI representation
+ * (in order to make controls behave logarithmically).
+ * 3. `internal' --- as passed to a processor, track, plugin, or whatever.
+ *
+ * Note that in some cases user and internal may be the same
+ * (and interface different) e.g. frequency, which is presented
+ * to the user and passed to the processor in linear terms, but
+ * which needs log scaling in the interface.
+ *
+ * In other cases, user and interface may be the same (and internal different)
+ * e.g. gain, which is presented to the user in log terms (dB)
+ * but passed to the processor as a linear quantity.
  */
 class LIBPBD_API Controllable : public PBD::StatefulDestructible, public boost::enable_shared_from_this<Controllable>
 {
@@ -65,47 +81,34 @@ public:
 
 	Controllable (const std::string& name, Flag f = Flag (0));
 
-	/* We express Controllable values in one of three ways:
-	 * 1. `user' --- as presented to the user (e.g. dB, Hz, etc.)
-	 * 2. `interface' --- as used in some cases for the UI representation
-	 * (in order to make controls behave logarithmically).
-	 * 3. `internal' --- as passed to a processor, track, plugin, or whatever.
-	 *
-	 * Note that in some cases user and internal may be the same
-	 * (and interface different) e.g. frequency, which is presented
-	 * to the user and passed to the processor in linear terms, but
-	 * which needs log scaling in the interface.
-	 *
-	 * In other cases, user and interface may be the same (and internal different)
-	 * e.g. gain, which is presented to the user in log terms (dB)
-	 * but passed to the processor as a linear quantity.
-	 */
-
-	/* Within an application, various Controllables might be considered to
+	/** Within an application, various Controllables might be considered to
 	 * be "grouped" in a way that implies that setting 1 of them also
 	 * modifies others in the group.
 	 */
-
 	enum GroupControlDisposition {
-		InverseGroup,  /* set all controls in the same "group" as this one */
-		NoGroup,     /* set only this control */
-		UseGroup,     /* use group settings to decide which group controls are altered */
-		ForGroup     /* this setting is being done *for* the group
-		                (i.e. UseGroup was set in the callchain
-		                somewhere).
-		             */
+		InverseGroup,  /**< set all controls in the same "group" as this one */
+		NoGroup,       /**< set only this control */
+		UseGroup,      /**< use group settings to decide which group controls are altered */
+		ForGroup       /**< this setting is being done *for* the group (i.e. UseGroup was set in the callchain somewhere). */
 	};
 
-	/** Get and Set `internal' value
+	/** Set `internal' value
 	 *
 	 * All derived classes must implement this.
 	 *
-	 * Basic derived classes will ignore @param group_override,
+	 * Basic derived classes will ignore \param group_override
 	 * but more sophisticated children, notably those that
 	 * proxy the value setting logic via an object that is aware of group
 	 * relationships between this control and others, will find it useful.
+	 *
+	 * @param value raw numeric value to set
+	 * @param group_override if and how to propagate value to grouped controls
+	 */
+	virtual void set_value (double value, GroupControlDisposition group_override) = 0;
+
+	/** Get `internal' value
+	 * @return raw value as used for the plugin/processor control port
 	 */
-	virtual void set_value (double, GroupControlDisposition group_override) = 0;
 	virtual double get_value (void) const = 0;
 
 	/** This is used when saving state. By default it just calls
@@ -189,7 +192,7 @@ public:
 	IgnorableControllable () : PBD::Controllable ("ignoreMe") {}
 	~IgnorableControllable () {}
 
-	void set_value (double /*v*/, PBD::Controllable::GroupControlDisposition /* group_override */) {}
+	void set_value (double v, PBD::Controllable::GroupControlDisposition group_override) {}
 	double get_value () const { return 0.0; }
 };
 
diff --git a/libs/pbd/pbd/crossthread.h b/libs/pbd/pbd/crossthread.h
index f69672b220..45e841fe87 100644
--- a/libs/pbd/pbd/crossthread.h
+++ b/libs/pbd/pbd/crossthread.h
@@ -34,11 +34,11 @@
 
 
 /** A simple abstraction of a mechanism of signalling one thread from another.
- * The signaller calls ::wakeup() to tell the signalled thread to check for
+ * The signaller calls \ref wakeup() to tell the signalled thread to check for
  * work to be done.
  *
- * This implementation provides both ::selectable() for use in direct
- * poll/select-based event loops, and a Glib::IOSource via ::ios() for use
+ * This implementation provides both selectable() for use in direct
+ * poll/select-based event loops, and a Glib::IOSource via ios() for use
  * in Glib main loop based situations.
  */
 
@@ -56,7 +56,7 @@ public:
 	void wakeup();
 
 	/* if the listening thread cares about the precise message
-	 * it is being sent, then ::deliver() can be used to send
+	 * it is being sent, then \ref deliver() can be used to send
 	 * a single byte message rather than a simple wakeup. These
 	 * two mechanisms should not be used on the same CrossThreadChannel
 	 * because there is no way to know which byte value will be used
@@ -64,8 +64,8 @@ public:
 	 */
 	int deliver (char msg);
 
-	/** if using ::deliver() to wakeup the listening thread, then
-	 * the listener should call ::receive() to fetch the message
+	/** if using \ref deliver() to wakeup the listening thread, then
+	 * the listener should call \ref receive() to fetch the message
 	 * type from the channel.
 	 *
 	 * wait = true only make sense for non_blocking channels,
diff --git a/libs/pbd/pbd/rcu.h b/libs/pbd/pbd/rcu.h
index 16008ffec0..4a42e5a3f6 100644
--- a/libs/pbd/pbd/rcu.h
+++ b/libs/pbd/pbd/rcu.h
@@ -27,22 +27,24 @@
 
 #include "pbd/libpbd_visibility.h"
 
-/** @file Defines a set of classes to implement Read-Copy-Update.  We do not attempt to define RCU here - use google.
-
-   The design consists of two parts: an RCUManager and an RCUWriter.
+/** @file rcu.h
+ * Define a set of classes to implement Read-Copy-Update.  We do not attempt to define RCU here - use google.
+ *
+ * The design consists of two parts: an RCUManager and an RCUWriter.
 */
 
 /** An RCUManager is an object which takes over management of a pointer to another object.
-   It provides three key methods:
-
-           - reader() : obtains a shared pointer to the managed object that may be used for reading, without synchronization
-	       - write_copy() : obtains a shared pointer to the object that may be used for writing/modification
-	       - update() : accepts a shared pointer to a (presumed) modified instance of the object and causes all
-	                    future reader() and write_copy() calls to use that instance.
-
-   Any existing users of the value returned by reader() can continue to use their copy even as a write_copy()/update() takes place.
-   The RCU manager will manage the various instances of "the managed object" in a way that is transparent to users of the manager
-   and managed object.
+ *
+ * It provides three key methods:
+ *
+ * - reader()     : obtains a shared pointer to the managed object that may be used for reading, without synchronization
+ * - write_copy() : obtains a shared pointer to the object that may be used for writing/modification
+ * - update()     : accepts a shared pointer to a (presumed) modified instance of the object and causes all
+ *                  future reader() and write_copy() calls to use that instance.
+ *
+ * Any existing users of the value returned by reader() can continue to use their copy even as a write_copy()/update() takes place.
+ * The RCU manager will manage the various instances of "the managed object" in a way that is transparent to users of the manager
+ * and managed object.
 */
 template<class T>
 class /*LIBPBD_API*/ RCUManager