From 54b8be72fd07bb51568ad5c4bad678b081a8dbe5 Mon Sep 17 00:00:00 2001
From: Josh Blum <josh@joshknows.com>
Date: Wed, 29 Jun 2011 11:26:33 -0700
Subject: uhd: properties tweaks and docs

---
 host/include/uhd/property_tree.hpp | 37 +++++++++++++++++++++++++++----------
 host/include/uhd/property_tree.ipp |  8 ++++----
 2 files changed, 31 insertions(+), 14 deletions(-)

(limited to 'host/include')

diff --git a/host/include/uhd/property_tree.hpp b/host/include/uhd/property_tree.hpp
index 63cd76a56..b20f3b779 100644
--- a/host/include/uhd/property_tree.hpp
+++ b/host/include/uhd/property_tree.hpp
@@ -35,15 +35,17 @@ template <typename T> class UHD_API property : boost::noncopyable{
 public:
     typedef boost::function<void(const T &)> subscriber_type;
     typedef boost::function<T(void)> publisher_type;
-    typedef boost::function<T(const T &)> master_type;
+    typedef boost::function<T(const T &)> coercer_type;
 
     /*!
-     * Register a master subscriber into the property.
-     * A master is a special subscriber that coerces the value.
-     * Only one master may be registered per property.
-     * Registering a master replaces the previous master.
+     * Register a coercer into the property.
+     * A coercer is a special subscribes that coerces the value.
+     * Only one coercer may be registered per property.
+     * Registering a coercer replaces the previous coercer.
+     * \param coercer the coercer callback function
+     * \return a reference to this property for chaining
      */
-    virtual property<T> &subscribe_master(const master_type &master) = 0;
+    virtual property<T> &coerce(const coercer_type &coercer) = 0;
 
     /*!
      * Register a publisher into the property.
@@ -51,6 +53,8 @@ public:
      * Publishers are useful for creating read-only properties.
      * Only one publisher may be registered per property.
      * Registering a publisher replaces the previous publisher.
+     * \param publisher the publisher callback function
+     * \return a reference to this property for chaining
      */
     virtual property<T> &publish(const publisher_type &publisher) = 0;
 
@@ -58,19 +62,32 @@ public:
      * Register a subscriber into the property.
      * All subscribers are called when the value changes.
      * Once a subscriber is registered, it cannot be unregistered.
+     * \param subscriber the subscriber callback function
+     * \return a reference to this property for chaining
      */
     virtual property<T> &subscribe(const subscriber_type &subscriber) = 0;
 
-    //! Update calls all subscribers w/ the current value
+    /*!
+     * Update calls all subscribers w/ the current value.
+     * \return a reference to this property for chaining
+     */
     virtual property<T> &update(void) = 0;
 
     /*!
      * Set the new value and call all subscribers.
-     * The master is called first to coerce the value.
+     * The coercer (when provided) is called initially,
+     * and the coerced value is used to set the subscribers.
+     * \param value the new value to set on this property
+     * \return a reference to this property for chaining
      */
     virtual property<T> &set(const T &value) = 0;
 
-    //! Get the current value of this property
+    /*!
+     * Get the current value of this property.
+     * The publisher (when provided) yields the value,
+     * otherwise an internal shadow is used for the value.
+     * \return the current value in the property
+     */
     virtual T get(void) const = 0;
 };
 
@@ -100,7 +117,7 @@ public:
     //! Get access to a property in the tree
     template <typename T> property<T> &access(const path_type &path);
 
-protected:
+private:
     //! Internal create property with wild-card type
     virtual void _create(const path_type &path, const boost::shared_ptr<void> &prop) = 0;
 
diff --git a/host/include/uhd/property_tree.ipp b/host/include/uhd/property_tree.ipp
index 3dba6fb28..5fbb2dda5 100644
--- a/host/include/uhd/property_tree.ipp
+++ b/host/include/uhd/property_tree.ipp
@@ -29,8 +29,8 @@ namespace uhd{ namespace /*anon*/{
 template <typename T> class UHD_API property_impl : public property<T>{
 public:
 
-    property<T> &subscribe_master(const typename property<T>::master_type &master){
-        _master = master;
+    property<T> &coerce(const typename property<T>::coercer_type &coercer){
+        _coercer = coercer;
         return *this;
     }
 
@@ -50,7 +50,7 @@ public:
     }
 
     property<T> &set(const T &value){
-        _value = boost::shared_ptr<T>(new T(_master.empty()? value : _master(value)));
+        _value = boost::shared_ptr<T>(new T(_coercer.empty()? value : _coercer(value)));
         BOOST_FOREACH(typename property<T>::subscriber_type &subscriber, _subscribers){
             subscriber(*_value); //let errors propagate
         }
@@ -64,7 +64,7 @@ public:
 private:
     std::vector<typename property<T>::subscriber_type> _subscribers;
     typename property<T>::publisher_type _publisher;
-    typename property<T>::master_type _master;
+    typename property<T>::coercer_type _coercer;
     boost::shared_ptr<T> _value;
 };
 
-- 
cgit v1.2.3