added a bunch of documentation to plugin related headers

diff --git a/lib/abstractroutingengine.h b/lib/abstractroutingengine.h
index 3448fce..abd1d34 100644 (file)
--- a/lib/abstractroutingengine.h
+++ b/lib/abstractroutingengine.h
@@ -40,6 +40,11 @@ class AsyncRangePropertyReply;
 typedef std::function<void (AsyncPropertyReply*)> GetPropertyCompletedSignal;
 typedef std::function<void (AsyncRangePropertyReply*)> GetRangedPropertyCompletedSignal;
 
+/*!
+ * \brief The AsyncPropertyRequest class is used by sinks to request property values.
+ * \see AbstractRoutingEngine::getPropertyAsync
+ * \see AsyncPropertyReply
+ */
 class AsyncPropertyRequest
 {
 public:
@@ -71,13 +76,43 @@ public:
 
        virtual ~AsyncPropertyRequest() { }
 
+       /*!
+        * \brief property property to request.
+        */
        VehicleProperty::Property property;
+
+       /*!
+        * \brief sourceUuidFilter the requesting sink should use this to filter on a specific source or leave blank to use any source
+        */
        std::string sourceUuidFilter;
+
+       /*!
+        * \brief zoneFilter the requesting sink should use this if he wants to filter on a specific zone
+        */
        Zone::Type zoneFilter;
+
+       /*!
+        * \brief completed the callback when the request has been completed.
+        */
        GetPropertyCompletedSignal completed;
+
+       /*!
+        * \brief use to specify a timeout in ms for the request.  When a timeout occurs, the 'completed' callback
+        * will be called with an error.  @see AsyncPropertyReply
+        * default value is: 10000 ms
+        */
        uint timeout;
 };
 
+/*!
+ * \brief The AsyncPropertyReply class is used by sources to reply to Get and Set operations.  The source should
+ * set success to true if the call is successful or 'false' if the request was not successful and set 'error'
+ * to the appropriate error.
+ * \see AbstractRoutingEngine::getPropertyAsync
+ * \see AsyncPropertyReply
+ * \see AbstractSource::Operations
+ * \see AbstractSource::getPropertyAsync
+ */
 class AsyncPropertyReply: public AsyncPropertyRequest
 {
 public:
@@ -92,6 +127,9 @@ public:
                }
        }
 
+       /*!
+        * \brief The Error enum
+        */
        enum Error {
                NoError = 0,
                Timeout,
@@ -100,17 +138,33 @@ public:
                ZoneNotSupported
        };
 
-       /**
-        * @brief value of the reply.  This may be null if success = false.  This is owned by the source.
+       /*!
+        * \brief value of the reply.  This may be null if success = false.  This is owned by the source.
         */
        AbstractPropertyType* value;
+
+       /*!
+        * \brief success indicates if the request was successfull or not.  True means success.  False means fail and the 'error'
+        * member should be set.
+        */
        bool success;
+
+       /*!
+        * \brief error contains the error if the request was not successful.\
+        * \see Error
+        */
        Error error;
 
 private:
        GSource* timeoutSource;
 };
 
+/*!
+ * \brief The AsyncSetPropertyRequest class is used by sinks to set a property to the 'value'.  The source will reply
+ * with a AsyncPropertyReply containing the new value or an error
+ * \see AbstractRoutingEngine::setProperty
+ * \see AsyncPropertyReply
+ */
 class AsyncSetPropertyRequest: public AsyncPropertyRequest
 {
 public:
@@ -128,9 +182,16 @@ public:
 
        virtual ~AsyncSetPropertyRequest() { }
 
+       /*!
+        * \brief value the new value to set the property to.
+        */
        AbstractPropertyType* value;
 };
 
+/*!
+ * \brief The AsyncRangePropertyRequest class is used by sinks to request values within a time or sequence range
+ * \see AbstractRoutingEngine::getRangePropertyAsync
+ */
 class AsyncRangePropertyRequest
 {
 public:
@@ -141,7 +202,6 @@ public:
        }
 
        AsyncRangePropertyRequest(const AsyncRangePropertyRequest &request)
-
        {
                this->properties = request.properties;
                this->completed = request.completed;
@@ -154,15 +214,51 @@ public:
 
        virtual ~AsyncRangePropertyRequest() {}
 
+       /*!
+        * \brief properties list of properties to request
+        */
        PropertyList properties;
+
+       /*!
+        * \brief sourceUuid if the sink wishes to request a specific source, this should be set to the uuid of the source.
+        */
        std::string sourceUuid;
+
+       /*!
+        * \brief completed callback that is called when the ranged request is complete.
+        */
        GetRangedPropertyCompletedSignal completed;
+
+       /*!
+        * \brief timeBegin set this to request values for the specified property beggining at this time.  Time is seconds\
+        * since the unix epoc.  Set this to '0' if you do not want values within a time range.
+        */
        double timeBegin;
+
+       /*!
+        * \brief timeEnd set this to request values for the specified property beggining at this time.  Time is seconds\
+        * since the unix epoc.  Set this to '0' if you do not want values within a time range.
+        */
        double timeEnd;
+
+       /*!
+        * \brief sequenceBegin set this to request values with a sequence >= to the sequenceBegin value.  Set to -1 if
+        * you don't want values within a sequence ranges.
+        */
        int32_t sequenceBegin;
+
+       /*!
+        * \brief sequenceEnd set this to request values with a sequence <= to the sequenceEnd value.  Set to -1 if
+        * you don't want values within a sequence ranges.
+        */
        int32_t sequenceEnd;
 };
 
+/*!
+ * \brief The AsyncRangePropertyReply class is used by a source to reply to an AsyncRangePropertyRequest.
+ * the source should set success to 'true' and populate the 'values' member if the request was successful.
+ * If the request is not successful, 'success' should be set to 'false' and the 'error' member should be set.
+ */
 class AsyncRangePropertyReply: public AsyncRangePropertyRequest
 {
 public:
@@ -182,9 +278,19 @@ public:
                values.clear();
        }
 
+       /*!
+        * \brief error this is set if there was an error in the request.  "success" will also be set to false.
+        */
        AsyncPropertyReply::Error error;
 
+       /*!
+        * \brief values if the request was successful, this will contain a list of values meeting the criteria of the request.
+        */
        std::list<AbstractPropertyType*> values;
+
+       /*!
+        * \brief success this will be true if the request was successful.  If not, this is false and error is set.
+        */
        bool success;
 };
 
@@ -211,19 +317,19 @@ public:
        virtual void  unregisterSink(AbstractSink* self) = 0;
 
        /**
-        * @brief sourcesForProperty
-        * @param property
-        * @return list of source uuid's that support the "property"
+        * /brief sourcesForProperty
+        * /param property
+        * /return list of source uuid's that support the "property"
         */
        virtual std::list<std::string> sourcesForProperty(VehicleProperty::Property property) = 0;
 
        /**
-        * @brief getPropertyAsync requests a property value from a source.  This call has a timeout and will always return.
-        * @see AsyncPropertyRequest
-        * @see AsyncPropertyReply.
-        * @param request requested property.
-        * @return AsyncPropertyReply. The returned AsyncPropertyReply is owned by the caller of getPropertyAsync.
-        * @example AsyncPropertyRequest request;
+        * /brief getPropertyAsync requests a property value from a source.  This call has a timeout and will always return.
+        * /see AsyncPropertyRequest
+        * /see AsyncPropertyReply.
+        * /param request requested property.
+        * /return AsyncPropertyReply. The returned AsyncPropertyReply is owned by the caller of getPropertyAsync.
+        * /example AsyncPropertyRequest request;
         * request.property = VehicleProperty::VehicleSpeed
         * request.completed = [](AsyncPropertyReply* reply) { delete reply; };
         * routingEngine->getPropertyAsync(request);

diff --git a/lib/abstractsink.cpp b/lib/abstractsink.cpp
index a8ec558..87d5509 100644 (file)
--- a/lib/abstractsink.cpp
+++ b/lib/abstractsink.cpp
@@ -31,11 +31,6 @@ AbstractSink::~AbstractSink()
        routingEngine->unregisterSink(this);
 }
 
-void AbstractSink::setConfiguration(map<string, string> config)
-{
-       configuration = config;
-}
-
 AbstractSinkManager::AbstractSinkManager(AbstractRoutingEngine* engine, map<string, string> config)
 :routingEngine(engine)
 {

diff --git a/lib/abstractsink.h b/lib/abstractsink.h
index a98f44e..40bd9ee 100644 (file)
--- a/lib/abstractsink.h
+++ b/lib/abstractsink.h
@@ -67,12 +67,15 @@ public:
          */
        virtual void propertyChanged(AbstractPropertyType* value, const string &uuid) {}
 
+       /*! supportedChanged() is called when the supported properties changes
+        * @arg supportedProperties the new list of supported properties.
+        */
        virtual void supportedChanged(PropertyList supportedProperties) = 0;
        
-
-       virtual void setConfiguration(map<string, string> config);
-
 protected:
+       /*!
+        * \brief routingEngine is the core of AMB.  It is used to pass plugin and property information to other plugins
+        */
        AbstractRoutingEngine* routingEngine;
        map<string, string> configuration;
 };

diff --git a/lib/abstractsource.h b/lib/abstractsource.h
index eae6c5b..c571976 100644 (file)
--- a/lib/abstractsource.h
+++ b/lib/abstractsource.h
@@ -42,6 +42,9 @@ class AbstractSource: public AbstractSink
 {
 
 public:
+       /*!
+        * \brief The Operations enum is a bitmask flag used to specify which operations are supported by the source plugin
+        */
        enum Operations {
                Get = 0x01,
                Set = 0x02,
@@ -53,19 +56,70 @@ public:
        
        ///pure virtual methods:
 
+       /*!
+        * \brief getPropertyAsync is called when a sink requests the value for given property.
+        * This is only called if the source supports the Get operation (@see Operation)
+        * \param reply the reply variable.  @see AsyncPropertyReply
+        */
        virtual void getPropertyAsync(AsyncPropertyReply *reply) = 0;
+
+       /*!
+        * \brief getRangePropertyAsync is called when a sink requests a series of values for a given
+        * property within a specified time or sequencial range.  This will only be called if the source
+        * support the Ranged Operation (@see Operations)
+        * \param reply is the reply variable.  @see AsyncRangePropertyReply
+        */
        virtual void getRangePropertyAsync(AsyncRangePropertyReply *reply) = 0;
+
+       /*!
+        * \brief setProperty is called when a sink requests to set a value for a given property.
+        * This is only called if the source supports the Set Operation (@see Operation)
+        * \param request the requested property to set.
+        * \return returns a pointer to the new value for the property.  @see AsyncPropertyReply
+        */
        virtual AsyncPropertyReply * setProperty(AsyncSetPropertyRequest request) = 0;
+
+       /*!
+        * \brief subscribeToPropertyChanges is called when a sink requests a subscription.  Source plugins
+        * can keep track of subscriptions and may wish to sleep if there are no subscriptions.
+        * \param property the property that is being subscribed.
+        * @see unsubscribeToPropertyChanges
+        */
        virtual void subscribeToPropertyChanges(VehicleProperty::Property property) = 0;
+
+       /*!
+        * \brief unsubscribeToPropertyChanges is called when a sink requests to unsubscribe from a given property's changes.
+        * \param property the property to unsubscribe to
+        * @see subscribeToPropertyChanges
+        */
        virtual void unsubscribeToPropertyChanges(VehicleProperty::Property property) = 0;
+
+       /*!
+        * \brief supported is called by the routingEngine (@see AbstractRoutingEngine) to understand what properties this source supports
+        * \return returns a list of supported properties.  If the the supported properties changed, the source should call AbstractRoutingEngine::setSupported.
+        */
        virtual PropertyList supported() = 0;
 
+       /*!
+        * \brief supportedOperations
+        * \return returns the supported operations.  @see Operations
+        */
        virtual int supportedOperations() = 0;
 
+       /*!
+        * \brief getPropertyInfo used to return specific information about a property @see PropertyInfo
+        * the source should override this otherwise a PropertyInfo::invalid() will be returned for the property
+        * \param property the property to get info for.
+        * \return a PropertyInfo object.
+        */
        virtual PropertyInfo getPropertyInfo(VehicleProperty::Property property);
        
 
 protected:
+       /*!
+        * \brief routingEngine the core routing engine used to send property updates to sink plugins.
+        * @see AbstractRoutingEngine
+        */
        AbstractRoutingEngine* routingEngine;
        
 private:

diff --git a/plugins/demosink/demosinkplugin.h b/plugins/demosink/demosinkplugin.h
index 755b5c5..c19331d 100644 (file)
--- a/plugins/demosink/demosinkplugin.h
+++ b/plugins/demosink/demosinkplugin.h
@@ -50,7 +50,6 @@ public:
        :AbstractSinkManager(engine, config)
        {
                DemoSink* sink = new DemoSink(routingEngine, config);
-               sink->setConfiguration(config);
        }
 
        void setConfiguration(map<string, string> config)