Clarify commentary slightly. No functional changes.

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

2 files changed, 76 insertions, 42 deletions

diff --git a/libs/pbd/pbd/properties.h b/libs/pbd/pbd/properties.h
index ad9ed2f1f6..d961046760 100644
--- a/libs/pbd/pbd/properties.h
+++ b/libs/pbd/pbd/properties.h
@@ -33,8 +33,7 @@
 
 namespace PBD {
 
-/** Parent class for classes which represent a single scalar property in a Stateful object 
- */
+/** Parent class for classes which represent a single scalar property in a Stateful object */
 template<class T>
 class PropertyTemplate : public PropertyBase
 {
@@ -58,6 +57,9 @@ public:
 		, _current (s._current)
 	{}
 
+
+	/* OPERATORS / ACCESSORS */
+
 	T & operator=(T const& v) {
 		set (v);
 		return _current;
@@ -93,16 +95,9 @@ public:
 		return _current;
 	}
 
-	void clear_changes () {
-		_have_old = false;
-	}
-
-	void get_changes_as_xml (XMLNode* history_node) const {
-		XMLNode* node = history_node->add_child (property_name());
-                node->add_property ("from", to_string (_old));
-                node->add_property ("to", to_string (_current));
-	}
 
+	/* MANAGEMENT OF Stateful State */
+	
 	bool set_value (XMLNode const & node) {
 
 		XMLProperty const* p = node.property (property_name());
@@ -123,27 +118,46 @@ public:
                 node.add_property (property_name(), to_string (_current));
 	}
 
-	bool changed () const { return _have_old; }
 	
-	void apply_changes (PropertyBase const * p) {
-		T v = dynamic_cast<const PropertyTemplate<T>* > (p)->val ();
-		if (v != _current) {
-			set (v);
-		}
+	/* MANAGEMENT OF HISTORY */
+	
+	void clear_changes () {
+		_have_old = false;
 	}
 
+	bool changed () const { return _have_old; }
+
 	void invert () {
 		T const tmp = _current;
 		_current = _old;
 		_old = tmp;
 	}
 
+
+	/* TRANSFERRING HISTORY TO / FROM A StatefulDiffCommand */
+	
+	void get_changes_as_xml (XMLNode* history_node) const {
+		XMLNode* node = history_node->add_child (property_name());
+                node->add_property ("from", to_string (_old));
+                node->add_property ("to", to_string (_current));
+	}
+
 	void get_changes_as_properties (PropertyList& changes, Command *) const {
 		if (this->_have_old) {
 			changes.add (clone ());
 		}
 	}
 
+
+	/* VARIOUS */
+
+	void apply_changes (PropertyBase const * p) {
+		T v = dynamic_cast<const PropertyTemplate<T>* > (p)->val ();
+		if (v != _current) {
+			set (v);
+		}
+	}
+
 protected:
 
 	void set (T const& v) {
diff --git a/libs/pbd/pbd/property_basics.h b/libs/pbd/pbd/property_basics.h
index 2c35c4bbc2..2255a3d79b 100644
--- a/libs/pbd/pbd/property_basics.h
+++ b/libs/pbd/pbd/property_basics.h
@@ -38,11 +38,11 @@ typedef GQuark PropertyID;
 
 template<typename T>
 struct PropertyDescriptor {
-    PropertyDescriptor () : property_id (0) {}
-    PropertyDescriptor (PropertyID pid) : property_id (pid) {}
-
-    PropertyID property_id;
-    typedef T value_type;
+	PropertyDescriptor () : property_id (0) {}
+	PropertyDescriptor (PropertyID pid) : property_id (pid) {}
+	
+	PropertyID property_id;
+	typedef T value_type;
 };
 
 /** A list of IDs of Properties that have changed in some situation or other */
@@ -78,7 +78,11 @@ public:
 	template<typename T> void add (PropertyDescriptor<T> p);
 };
 
-/** Base (non template) part of Property */
+/** Base (non template) part of Property
+ *  Properties are used for two main reasons:
+ *    - to handle current state (when serializing Stateful objects)
+ *    - to handle history since some operation was started (when making StatefulDiffCommands for undo)
+ */
 class PropertyBase
 {
 public:
@@ -88,18 +92,45 @@ public:
 
 	virtual ~PropertyBase () {}
 
-	virtual PropertyBase* clone () const = 0;
-        
+
+	/* MANAGEMENT OF Stateful STATE */
+
+	/** Set the value of this property from a Stateful node.
+	 *  @return true if the value was set.
+	 */
+	virtual bool set_value (XMLNode const &) = 0;
+
+	/** Get this property's value and put it into a Stateful node */
+	virtual void get_value (XMLNode& node) const = 0;
+
+
+	/* MANAGEMENT OF HISTORY */
+
 	/** Forget about any old changes to this property's value */
 	virtual void clear_changes () = 0;
 
 	/** Tell any things we own to forget about their old values */
 	virtual void clear_owned_changes () {}
 
-        /** Get any changes in this property as XML and add them to a node */
+	/** @return true if this property has changed in value since construction or since
+	 *  the last call to clear_changes (), whichever was more recent.
+	 */
+	virtual bool changed () const = 0;
+
+	/** Invert the changes in this property */
+	virtual void invert () = 0;
+	
+
+	/* TRANSFERRING HISTORY TO / FROM A StatefulDiffCommand */
+
+        /** Get any changes in this property as XML and add them to a
+	 *  StatefulDiffCommand node.
+	 */
 	virtual void get_changes_as_xml (XMLNode *) const = 0;
 	
-        /** Get any changes in this property as Properties and add them to a list */
+        /** If this Property has changed, clone it and add it to a given list.
+	 *  Used for making StatefulDiffCommands.
+	 */
 	virtual void get_changes_as_properties (PropertyList& changes, Command *) const = 0;
 
 	/** Collect StatefulDiffCommands for changes to anything that we own */
@@ -110,25 +141,14 @@ public:
 	 */
         virtual PropertyBase* clone_from_xml (const XMLNode &) const { return 0; }
 
-	/** Set our value from an XML node.
-	 *  @return true if the value was set.
-	 */
-	virtual bool set_value (XMLNode const &) = 0;
-
-	/** Get our value and put it into an XML node */
-	virtual void get_value (XMLNode& node) const = 0;
 
-	/** @return true if this property has changed in value since construction or since
-	 *  the last call to clear_changes (), whichever was more recent.
-	 */
-	virtual bool changed() const = 0;
+	/* VARIOUS */
+	
+	virtual PropertyBase* clone () const = 0;
 
-	/** Apply changes contained in another Property to this one */
+	/** Set this property's current state from another */
 	virtual void apply_changes (PropertyBase const *) = 0;
 
-	/** Invert the changes in this property */
-	virtual void invert () = 0;
-
 	const gchar* property_name () const { return g_quark_to_string (_property_id); }
 	PropertyID   property_id () const   { return _property_id; }