Update documentation after review.

Jojo-1000 · Moritz Wirger
1 parent b74756e3
Showing 11 changed files with 26 additions and 5 deletions
include/hueplusplus/BaseDevice.h
include/hueplusplus/Bridge.h
include/hueplusplus/BridgeConfig.h
include/hueplusplus/Group.h
include/hueplusplus/HueDeviceTypes.h
include/hueplusplus/Light.h
include/hueplusplus/ResourceList.h
include/hueplusplus/Rule.h
include/hueplusplus/Scene.h
include/hueplusplus/Schedule.h
include/hueplusplus/Sensor.h
@@ -120,9 +120,13 @@ public:
     virtual void refresh(bool force = false);
  
     //! \brief Sets custom refresh interval for this device.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     virtual void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration);
  
 protected:
+    //! \brief Protected ctor that is used by subclasses, construct with shared cache.
+    //! \param id Integer that specifies the id of this device
+    //! \param baseCache Cache of the ResourceList containing this device (must not be null).
     BaseDevice(int id, const std::shared_ptr<APICache>& baseCache);
     //! \brief Protected ctor that is used by subclasses.
     //!
@@ -164,6 +164,7 @@ public:
     void refresh();
  
     //! \brief Sets refresh interval for the whole bridge state.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration);
  
     //! \brief Function to get the ip address of the hue bridge
@@ -68,6 +68,7 @@ public:
     void refresh(bool force = false);
  
     //! \brief Sets custom refresh interval for the config.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration);
  
     //! \brief Get the list of whitelisted users
@@ -41,6 +41,9 @@ namespace hueplusplus
 class Group
 {
 public:
+    //! \brief Creates group with shared cache
+    //! \param id Group id in the bridge
+    //! \param baseCache Cache of the group list.
     Group(int id, const std::shared_ptr<APICache>& baseCache);
     //! \brief Creates group with id
     //! \param id Group id in the bridge
@@ -59,6 +62,7 @@ public:
     void refresh(bool force = false);
  
     //! \brief Sets custom refresh interval for this group.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration);
  
     //! \name General information
@@ -41,6 +41,7 @@ public:
     //! \brief Create a Light with the correct type from the JSON state.
     //! \param lightState Light JSON as returned from the bridge (not only the "state" part of it).
     //! \param id Light id.
+    //! \param baseCache Optional shared cache for the light.
     //! \returns Light with matching id, strategies and \ref ColorType.
     //! \throws std::system_error when system or socket operations fail
     //! \throws HueException when light type is unknown
@@ -554,7 +554,7 @@ public:
     ///@}
  
 protected:
-    //! \brief Protected ctor that is used by \ref Bridge class.
+    //! \brief Protected ctor that is used by \ref LightFactory.
     //!
     //! \param id Integer that specifies the id of this light
     //! \param commands HueCommandAPI for communication with the bridge
@@ -562,9 +562,15 @@ protected:
     //! leaves strategies unset
     Light(int id, const HueCommandAPI& commands);
  
+    //! \brief Protected ctor that is used by \ref LightFactory.
+    //!
+    //! \param id Integer that specifies the id of this light
+    //! \param baseCache Cache of the light list (must not be null).
+    //!
+    //! leaves strategies unset
     Light(int id, const std::shared_ptr<APICache>& baseCache);
  
-    //! \brief Protected ctor that is used by \ref Bridge class, also sets
+    //! \brief Protected ctor that is used by \ref LightFactory, also sets
     //! strategies.
     //!
     //! \param id Integer that specifies the id of this light
@@ -46,9 +46,6 @@ template &lt;typename Resource, typename IdT&gt;
 class ResourceList
 {
 public:
-    struct SharedStateTag
-    { };
-
     using ResourceType = Resource;
     using IdType = IdT;
     static_assert(std::is_integral<IdType>::value || std::is_same<std::string, IdType>::value,
@@ -95,6 +92,7 @@ public:
     void refresh() { stateCache->refresh(); }
  
     //! \brief Sets custom refresh interval for this list and all resources created.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration)
     {
         stateCache->setRefreshDuration(refreshDuration);
@@ -59,6 +59,7 @@ public:
     void refresh(bool force = false);
  
     //! \brief Sets custom refresh interval for this rule.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration);
  
     //! \brief Get rule identifier
@@ -140,6 +140,7 @@ public:
     void refresh(bool force = false);
  
     //! \brief Sets custom refresh interval for this group.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration);
  
     //! \brief Get scene identifier
@@ -49,6 +49,7 @@ public:
     void refresh();
  
     //! \brief Sets custom refresh interval for this schedule.
+    //! \param refreshDuration The new minimum duration between refreshes. May be 0 or \ref c_refreshNever.
     void setRefreshDuration(std::chrono::steady_clock::duration refreshDuration);
  
     //! \brief Get schedule identifier
@@ -59,6 +59,9 @@ Alert alertFromString(const std::string&amp; s);
 class Sensor : public BaseDevice
 {
 public:
+    //! \brief Construct Sensor with shared cache
+    //! \param id Integer that specifies the id of this sensor
+    //! \param baseCache Cache of the SensorList.
     Sensor(int id, const std::shared_ptr<APICache>& baseCache);
  
     //! \brief Construct Sensor.