No-op: rename a few variables and add/fix some comments.

git-svn-id: svn://localhost/ardour2/branches/3.0@6818 d708f5d6-7413-0410-9779-e7cbd77b26cf

gtk2_ardour/automation_line.cc

@@ -625,7 +625,6 @@ struct ControlPointSorter
 };
 
 /** Common parts of starting a drag.
- *  @param d Description of the drag.
  *  @param x Starting x position in units, or 0 if x is being ignored.
  *  @param fraction Starting y position (as a fraction of the track height, where 0 is the bottom and 1 the top)
  */

gtk2_ardour/port_matrix_component.cc

@@ -24,7 +24,8 @@
 using namespace std;
 
 /** Constructor.
- *  @param p Port matrix that we're in.
+ *  @param m Port matrix that we're in.
+ *  @param b Port matrix body that we're in.
  */
 PortMatrixComponent::PortMatrixComponent (PortMatrix* m, PortMatrixBody* b)
 	: _matrix (m),

gtk2_ardour/public_editor.h

@@ -143,7 +143,7 @@ class PublicEditor : public Gtk::Window, public PBD::StatefulDestructible {
 	/** Set the mouse mode (gain, object, range, timefx etc.)
 	 * @param m Mouse mode (defined in editing_syms.h)
 	 * @param force Perform the effects of the change even if no change is required
-	 * (ie even if the current mouse mode is equal to \ref m)
+	 * (ie even if the current mouse mode is equal to @param m)
 	 */
 	virtual void set_mouse_mode (Editing::MouseMode m, bool force = false) = 0;
 
@@ -173,9 +173,9 @@ class PublicEditor : public Gtk::Window, public PBD::StatefulDestructible {
 	 */
 	virtual bool sound_notes () const = 0;
 
-	/** Possibly start the audition of a region.  If \ref r is 0, or not an AudioRegion
+	/** Possibly start the audition of a region.  If @param r is 0, or not an AudioRegion
-	 * any current audition is cancelled.  If we are currently auditioning \ref r,
+	 * any current audition is cancelled.  If we are currently auditioning @param r,
-	 * the audition will be cancelled.  Otherwise an audition of \ref r will start.
+	 * the audition will be cancelled.  Otherwise an audition of @param r will start.
 	 * \param r Region to consider.
 	 */
 	virtual void consider_auditioning (boost::shared_ptr<ARDOUR::Region> r) = 0;

libs/ardour/ardour/playlist.h

@@ -66,7 +66,7 @@ class RegionListProperty : public PBD::SequenceProperty<std::list<boost::shared_
         RegionListProperty (Playlist&);
 
         boost::shared_ptr<Region> lookup_id (const PBD::ID& id);
-        void diff (PBD::PropertyList& before, PBD::PropertyList& after) const;
+        void diff (PBD::PropertyList& undo, PBD::PropertyList& redo) const;
 
   private:
         friend class Playlist;

libs/ardour/ardour/processor.h

@@ -72,7 +72,7 @@ class Processor : public SessionObject, public AutomatableControls, public Laten
 	/** @param result_required true if, on return from this method, bufs is required to contain valid data;
 	 *  if false, the method need not bother writing to bufs if it doesn't want to.
 	 */  
-	virtual void run (BufferSet& /*bufs*/, sframes_t /*start_frame*/, sframes_t /*end_frame*/, nframes_t /*nframes*/, bool /*result_required*/) {}
+	virtual void run (BufferSet& /*bufs*/, sframes_t /*start_frame*/, sframes_t /*end_frame*/, nframes_t /*nframes*/, bool result_required) {}
 	virtual void silence (nframes_t /*nframes*/) {}
 
 	virtual void activate ()   { _pending_active = true; ActiveChanged(); }

libs/ardour/ardour/region_factory.h

@@ -66,8 +66,8 @@ class RegionFactory {
 	/** create a copy of @other starting at zero within @param other's sources */
 	static boost::shared_ptr<Region> create (boost::shared_ptr<Region> other, 
 						 const PBD::PropertyList&, bool announce = true);
-	/** create a copy of @other starting at @param offset within @param other */
+	/** create a copy of @param other starting at @param offset within @param other */
-	static boost::shared_ptr<Region> create (boost::shared_ptr<Region>, frameoffset_t offset, 
+	static boost::shared_ptr<Region> create (boost::shared_ptr<Region> other, frameoffset_t offset, 
 						 const PBD::PropertyList&, bool announce = true);
 	/** create a "copy" of @param other but using a different set of sources @param srcs */
 	static boost::shared_ptr<Region> create (boost::shared_ptr<Region> other, const SourceList& srcs, 

libs/ardour/ardour/slave.h

@@ -67,7 +67,7 @@ class Slave {
 	 *  and after the method call they should
 	 *
 	 * Session::follow_slave will then try to follow the given
-	 * <emph>position</emph> using a delay locked loop (DLL),
+	 * <em>position</em> using a delay locked loop (DLL),
 	 * starting with the first given transport speed.
 	 * If the values of speed and position contradict each other,
 	 * ARDOUR will always follow the position and disregard the speed.
@@ -153,7 +153,7 @@ class Slave {
 
 	/**
 	 * @return the number of frames that this slave wants to seek ahead. Relevant
-	 * only if @func requires_seekahead() returns true.
+	 * only if requires_seekahead() returns true.
 	 */
 
 	virtual nframes64_t seekahead_distance() const { return 0; }

libs/ardour/automation_list.cc

@@ -88,8 +88,8 @@ AutomationList::AutomationList (const AutomationList& other, double start, doubl
 	AutomationListCreated(this);
 }
 
-/** \a id is used for legacy sessions where the type is not present
+/** @param id is used for legacy sessions where the type is not present
- * in or below the <AutomationList> node.  It is used if \a id is non-null.
+ * in or below the AutomationList node.  It is used if @param id is non-null.
  */
 AutomationList::AutomationList (const XMLNode& node, Evoral::Parameter id)
 	: ControlList(id)

libs/ardour/playlist.cc

@@ -131,16 +131,18 @@ RegionListProperty::copy_for_history () const
 }
 
 void 
-RegionListProperty::diff (PropertyList& before, PropertyList& after) const
+RegionListProperty::diff (PropertyList& undo, PropertyList& redo) const
 {
         if (changed()) {
+		/* list of the removed/added regions since clear_history() was last called */
                 RegionListProperty* a = copy_for_history ();
-                RegionListProperty* b = copy_for_history ();
 
+		/* the same list, but with removed/added lists swapped (for undo purposes) */
+                RegionListProperty* b = copy_for_history ();
                 b->invert_changes ();
 
-                before.add (b);
+                undo.add (b);
-                after.add (a);
+                redo.add (a);
         }
 }
 

libs/pbd/pbd/properties.h

@@ -84,12 +84,10 @@ public:
 		_have_old = false;
 	}
 
-        /** If this property has been changed since the last clear_history() call
-            (or its construction), add an (XML) property describing the old value 
-            to the XMLNode @param old and another describing the current value to
-            the XMLNode @param current.
-        */
 	void add_history_state (XMLNode* history_node) const {
+		/* We can get to the current state of a scalar property like this one simply
+		   by knowing what the new state is.
+		*/
                 history_node->add_property (property_name(), to_string (_current));
 	}
 
@@ -167,10 +165,10 @@ public:
 		: PropertyTemplate<T> (q, v)
 	{}
         
-        void diff (PropertyList& before, PropertyList& after) const {
+        void diff (PropertyList& undo, PropertyList& redo) const {
                 if (this->_have_old) {
-                        before.add (new Property<T> (this->property_id(), this->_old));
+                        undo.add (new Property<T> (this->property_id(), this->_old));
-                        after.add (new Property<T> (this->property_id(), this->_current));
+                        redo.add (new Property<T> (this->property_id(), this->_current));
                 }
         }
 

libs/pbd/pbd/property_basics.h

@@ -28,6 +28,8 @@
 namespace PBD {
 
 class PropertyList;
+
+/** A unique identifier for a property of a Stateful object */
 typedef GQuark PropertyID;
 
 template<typename T>
@@ -39,6 +41,7 @@ struct PropertyDescriptor {
     typedef T value_type;
 };
 
+/** A list of IDs of Properties that have changed in some situation or other */
 class PropertyChange : public std::set<PropertyID>
 {
 public:
@@ -82,13 +85,29 @@ public:
 	/** Forget about any old value for this state */
 	virtual void clear_history () = 0;
 
-	virtual void add_history_state (XMLNode*)        const = 0;
+        /** Make XML that allows us to get from some previous state to the current state
-	virtual void diff (PropertyList&, PropertyList&) const = 0;
+	 *  of this property, and add it to @param history_node
+	 */
+	virtual void add_history_state (XMLNode* history_node) const = 0;
+
+	/** Add information to two property lists: one that allows
+	 *  undo of the changes in this property's state betwen now and
+	 *  the last call to clear_history, and one that allows redo
+	 *  of those changes.
+	 */
+	virtual void diff (PropertyList& undo, PropertyList& redo) const = 0;
         
         virtual PropertyBase* maybe_clone_self_if_found_in_history_node (const XMLNode&) const { return 0; }
 
+	/** Set state from an XML node previously generated by add_history_state */
 	virtual bool set_state_from_owner_state (XMLNode const&) = 0;
-	virtual void add_state_to_owner_state (XMLNode&) const   = 0;
+
+	/** Add complete current state in XML form to an existing XML node @param node */
+	virtual void add_state_to_owner_state (XMLNode& node) const = 0;
+
+	/** @return true if this property has changed in value since construction or since
+	 *  the last call to clear_history(), whichever was more recent.
+	 */
 	virtual bool changed() const = 0;
 
 	/** Set the value of this property from another */

libs/pbd/pbd/property_list.h

@@ -27,6 +27,8 @@
 class XMLNode;
 
 namespace PBD {
+
+/** A list of properties, mapped using their ID */	
 class PropertyList : public std::map<PropertyID, PropertyBase*>
 {
 public:
@@ -37,7 +39,7 @@ public:
         void add_history_state (XMLNode* before);
 
         /** Add a property (of some kind) to the list. Used when
-            constructing PropertyList's that describe a change/operation.
+            constructing PropertyLists that describe a change/operation.
         */
         bool add (PropertyBase* prop);
 

libs/pbd/pbd/sequence_property.h

@@ -1,3 +1,22 @@
+/*
+    Copyright (C) 2010 Paul Davis
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+*/
+
 #ifndef __libpbd_sequence_property_h__
 #define __libpbd_sequence_property_h__
 
@@ -15,12 +34,20 @@
 #include "i18n.h"
 
 namespace PBD {
+
+/** A base class for properties whose state is a container of other
+ *  things.  Its behaviour is `specialised' for this purpose in that
+ *  it holds state changes as additions to and removals from the
+ *  container, which is more efficient than storing entire state after
+ *  any change.
+ */
 template<typename Container>
 class SequenceProperty : public PropertyBase
 {
   public:
         typedef std::set<typename Container::value_type> ChangeContainer;
-	
+
+	/** A record of changes made */
         struct ChangeRecord { 
 	    ChangeContainer added;
 	    ChangeContainer removed;
@@ -36,7 +63,7 @@ class SequenceProperty : public PropertyBase
                 /* reverse the adds/removes so that this property's change member
                    correctly describes how to undo the changes it currently
                    reflects. A derived instance of this type of property will
-                   create a pdiff() pair by copying the property twice, and
+                   create a diff() pair by copying the property twice, and
                    calling this method on the "before" item of the pair.
                 */
 
@@ -44,6 +71,10 @@ class SequenceProperty : public PropertyBase
         }
 
 	void add_history_state (XMLNode* history_node) const {
+
+		/* We could record the whole of the current state here, but its
+		   obviously more efficient just to record what has changed.
+		*/
                 
                 XMLNode* child = new XMLNode (PBD::capitalize (property_name()));
                 history_node->add_child_nocopy (*child);

libs/pbd/pbd/stateful_diff_command.h

@@ -47,8 +47,8 @@ public:
 
 private:
 	boost::weak_ptr<Stateful> _object; ///< the object in question
-        PBD::PropertyList* _before; ///< its (partial) state before the command
+        PBD::PropertyList* _undo; ///< its (partial) state before the command, to allow undo
-        PBD::PropertyList* _after;  ///< its (partial) state after the operation
+        PBD::PropertyList* _redo;  ///< its (partial) state after the operation, to allow redo
 };
 
 };

libs/pbd/stateful.cc

@@ -175,7 +175,7 @@ Stateful::diff (PropertyList& before, PropertyList& after) const
 }
 
 /** Set state of some/all _properties from an XML node.
- *  @param node Node.
+ *  @param owner_state Node.
  *  @return PropertyChanges made.
  */
 PropertyChange
@@ -224,7 +224,7 @@ Stateful::set_properties (const PropertyList& property_list)
 }
 
 /** Add property states to an XML node.
- *  @param node Node.
+ *  @param owner_state Node.
  */
 void
 Stateful::add_properties (XMLNode& owner_state)

libs/pbd/stateful_diff_command.cc

@@ -34,35 +34,35 @@ using namespace PBD;
 
 StatefulDiffCommand::StatefulDiffCommand (boost::shared_ptr<Stateful> s)
 	: _object (s)
-        , _before (new PropertyList)
+        , _undo (new PropertyList)
-        , _after (new PropertyList)
+        , _redo (new PropertyList)
 {
-        s->diff (*_before, *_after);
+        s->diff (*_undo, *_redo);
 }
 
 StatefulDiffCommand::StatefulDiffCommand (boost::shared_ptr<Stateful> s, XMLNode const & n)
 	: _object (s)
-        , _before (0)
+        , _undo (0)
-        , _after (0)
+        , _redo (0)
 {
         const XMLNodeList& children (n.children());
 
         for (XMLNodeList::const_iterator i = children.begin(); i != children.end(); ++i) {
                 if ((*i)->name() == X_("Undo")) {
-                        _before = s->property_factory (**i);
+                        _undo = s->property_factory (**i);
                 } else if ((*i)->name() == X_("Do")) {
-                        _after = s->property_factory (**i);
+                        _redo = s->property_factory (**i);
                 }
         }
 
-        assert (_before != 0);
+        assert (_undo != 0);
-        assert (_after != 0);
+        assert (_redo != 0);
 }
 
 StatefulDiffCommand::~StatefulDiffCommand ()
 {
-        delete _before;
+        delete _undo;
-        delete _after;
+        delete _redo;
 }
 
 void
@@ -71,7 +71,7 @@ StatefulDiffCommand::operator() ()
 	boost::shared_ptr<Stateful> s (_object.lock());
 
 	if (s) {
-                PropertyChange changed = s->set_properties (*_after);
+                PropertyChange changed = s->set_properties (*_redo);
                 if (!changed.empty()) {
                         s->PropertyChanged (changed);
                 }
@@ -85,7 +85,7 @@ StatefulDiffCommand::undo ()
 
 	if (s) {
                 std::cerr << "Undoing a stateful diff command\n";
-                PropertyChange changed = s->set_properties (*_before);
+                PropertyChange changed = s->set_properties (*_undo);
                 if (!changed.empty()) {
                         std::cerr << "Sending changed\n";
                         s->PropertyChanged (changed);
@@ -108,14 +108,14 @@ StatefulDiffCommand::get_state ()
 	node->add_property ("obj-id", s->id().to_s());
 	node->add_property ("type-name", demangled_name (*s.get()));
 
-        XMLNode* before = new XMLNode (X_("Undo"));
+        XMLNode* undo = new XMLNode (X_("Undo"));
-        XMLNode* after = new XMLNode (X_("Do"));
+        XMLNode* redo = new XMLNode (X_("Do"));
 
-        _before->add_history_state (before);
+        _undo->add_history_state (undo);
-        _after->add_history_state (after);
+        _redo->add_history_state (redo);
         
-        node->add_child_nocopy (*before);
+        node->add_child_nocopy (*undo);
-        node->add_child_nocopy (*after);
+        node->add_child_nocopy (*redo);
 
 	return *node;
 }