yet more documentation..

3 files changed, 77 insertions, 4 deletions

diff --git a/libs/ardour/ardour/route.h b/libs/ardour/ardour/route.h
index 56f7ccdc99..7e7d5d55d4 100644
--- a/libs/ardour/ardour/route.h
+++ b/libs/ardour/ardour/route.h
@@ -266,8 +266,22 @@ class LIBARDOUR_API Route : public SessionObject, public Automatable, public Rou
 	boost::shared_ptr<Processor> before_processor_for_placement (Placement);
 	boost::shared_ptr<Processor> before_processor_for_index (int);
 	bool processors_reorder_needs_configure (const ProcessorList& new_order);
-	int remove_processor (boost::shared_ptr<Processor>, ProcessorStreams* err = 0, bool need_process_lock = true);
-	int replace_processor (boost::shared_ptr<Processor>, boost::shared_ptr<Processor>, ProcessorStreams* err = 0);
+	/** remove plugin/processor
+	 *
+	 * @param proc processor to remove
+	 * @param err error report (index where removal vailed, channel-count why it failed) may be nil
+	 * @param need_process_lock if locking is required (set to true, unless called from RT context with lock)
+	 * @returns 0 on success
+	 */
+	int remove_processor (boost::shared_ptr<Processor> proc, ProcessorStreams* err = 0, bool need_process_lock = true);
+	/** replace plugin/processor with another
+	 *
+	 * @param old processor to remove
+	 * @param sub processor to substitute the old one with
+	 * @param err error report (index where removal vailed, channel-count why it failed) may be nil
+	 * @returns 0 on success
+	 */
+	int replace_processor (boost::shared_ptr<Processor> old, boost::shared_ptr<Processor> sub, ProcessorStreams* err = 0);
 	int remove_processors (const ProcessorList&, ProcessorStreams* err = 0);
 	int reorder_processors (const ProcessorList& new_order, ProcessorStreams* err = 0);
 	void disable_processors (Placement);
@@ -280,10 +294,40 @@ class LIBARDOUR_API Route : public SessionObject, public Automatable, public Rou
 
 	bool strict_io () const { return _strict_io; }
 	bool set_strict_io (bool);
+	/** reset plugin-insert configuration to default, disable customizations.
+	 *
+	 * This is equivalent to calling
+	 * @code
+	 * customize_plugin_insert (proc, 0, unused)
+	 * @endcode
+	 *
+	 * @param proc Processor to reset
+	 * @returns true if successful
+	 */
 	bool reset_plugin_insert (boost::shared_ptr<Processor> proc);
+	/** enable custom plugin-insert configuration
+	 * @param proc Processor to customize
+	 * @param count number of plugin instances to use (if zero, reset to default)
+	 * @param outs output port customization
+	 * @returns true if successful
+	 */
 	bool customize_plugin_insert (boost::shared_ptr<Processor> proc, uint32_t count, ChanCount outs);
 	bool add_remove_sidechain (boost::shared_ptr<Processor> proc, bool);
+
+	/* enable sidechain input for a given processor
+	 *
+	 * The sidechain itself is an IO port object with variable number of channels and configured independently.
+	 * Adding/removing the port itself however requires reconfiguring the route and is hence
+	 * not a plugin operation itself.
+	 *
+	 * @param proc the processor to add sidechain inputs to
+	 * @returns true on success
+	 */
 	bool add_sidechain (boost::shared_ptr<Processor> proc) { return add_remove_sidechain (proc, true); }
+	/* remove sidechain input from given processor
+	 * @param proc the processor to remove the sidechain input from
+	 * @returns true on success
+	 */
 	bool remove_sidechain (boost::shared_ptr<Processor> proc) { return add_remove_sidechain (proc, false); }
 
 	framecnt_t set_private_port_latencies (bool playback) const;
diff --git a/libs/ardour/ardour/session.h b/libs/ardour/ardour/session.h
index 9f8102c928..137b6f04d6 100644
--- a/libs/ardour/ardour/session.h
+++ b/libs/ardour/ardour/session.h
@@ -875,14 +875,37 @@ class LIBARDOUR_API Session : public PBD::StatefulDestructible, public PBD::Scop
 	std::string next_undo() const { return _history.next_undo(); }
 	std::string next_redo() const { return _history.next_redo(); }
 
+	/** begin collecting undo information
+	 *
+	 * This call must always be followed by either
+	 * begin_reversible_command() or commit_reversible_command()
+	 *
+	 * @param cmd_name human readable name for the undo operation
+	 */
 	void begin_reversible_command (const std::string& cmd_name);
 	void begin_reversible_command (GQuark);
+	/** abort an open undo command
+	 * This must only be called after begin_reversible_command ()
+	 */
 	void abort_reversible_command ();
+	/** finalize an undo command and commit pending transactions
+	 *
+	 * This must only be called after begin_reversible_command ()
+	 * @param cmd (additional) command to add
+	 */
 	void commit_reversible_command (Command* cmd = 0);
 
 	void add_command (Command *const cmd);
 
-	PBD::StatefulDiffCommand* add_stateful_diff_command (boost::shared_ptr<PBD::StatefulDestructible>);
+	/** create an StatefulDiffCommand from the given object and add it to the stack.
+	 *
+	 * This function must only be called after  begin_reversible_command.
+	 * Failing to do so may lead to a crash.
+	 *
+	 * @param sfd the object to diff
+	 * @returns the allocated StatefulDiffCommand (already added via add_command)
+	 */
+	PBD::StatefulDiffCommand* add_stateful_diff_command (boost::shared_ptr<PBD::StatefulDestructible> sfd);
 
 	/** @return The list of operations that are currently in progress */
 	std::list<GQuark> const & current_operations () {
diff --git a/libs/ardour/ardour/track.h b/libs/ardour/ardour/track.h
index c49cbd00e2..b378021bce 100644
--- a/libs/ardour/ardour/track.h
+++ b/libs/ardour/ardour/track.h
@@ -116,7 +116,13 @@ class LIBARDOUR_API Track : public Route, public PublicDiskstream
 	 * @return true if the track can be bounced, or false otherwise.
 	 */
 	virtual bool bounceable (boost::shared_ptr<Processor> endpoint, bool include_endpoint) const = 0;
-	virtual boost::shared_ptr<Region> bounce (InterThreadInfo&) = 0;
+
+	/** bounce track from session start to session end to new region
+	 *
+	 * @param itt asynchronous progress report and cancel
+	 * @return a new audio region (or nil in case of error)
+	 */
+	virtual boost::shared_ptr<Region> bounce (InterThreadInfo& itt) = 0;
 
 	/** Bounce the given range to a new audio region.
 	 * @param start start time (in samples)