Update documentation for changed light access.

Jojo-1000 · Moritz Wirger
1 parent ea867228
Showing 3 changed files with 38 additions and 18 deletions
README.md
doc/markdown/Mainpage.md
include/hueplusplus/Hue.h
@@ -61,15 +61,15 @@ hueplusplus::Hue bridge(&quot;192.168.2.102&quot;, 80, &quot;&lt;username&gt;&quot;, handler);
  
 ### Controlling lights
 If you have your Bridge all set up, you can now control its lights.
-For that create a new HueLight object and call getLight(\<id\>) on your bridge object to get a reference to a specific light, where id
+For that create a new HueLight object and call lights().get(\<id\>) on your bridge object to get a reference to a specific light, where id
 is the id of the light set internally by the Hue Bridge.
 ```C++
-hueplusplus::HueLight light1 = bridge.getLight(1);
+hueplusplus::HueLight light1 = bridge.lights().get(1);
 ```
 If you don't know the id of a specific light or want to get an overview over all lights that are controlled by your bridge, 
-you can get a vector containing them by calling getAllLights() on your bridge object. If no lights are found the vector will be empty.
+you can get a vector containing them by calling getAll(). If no lights are found the vector will be empty.
 ```C++
-std::vector<std::reference_wrapper<hueplusplus::HueLight>> lights = bridge.getAllLights();
+std::vector<std::reference_wrapper<hueplusplus::HueLight>> lights = bridge.lights().getAll();
 ```
 If you now want to control a light, call a specific function of it.
 ```C++
@@ -57,15 +57,15 @@ hueplusplus::Hue bridge(&quot;192.168.2.102&quot;, 80, &quot;&lt;username&gt;&quot;, handler);
  
 ### Controlling lights
 If you have your Bridge all set up, you can now control its lights.
-For that create a new HueLight object and call [getLight(\<id\>)](@ref hueplusplus::Hue::getLight) on your bridge object to get a reference to a specific light, where id
+For that create a new HueLight object and call [lights().get(\<id\>)](@ref hueplusplus::ResourceList::get) on your bridge object to get a reference to a specific light, where id
 is the id of the light set internally by the Hue Bridge.
 ```{.cpp}
-hueplusplus::HueLight light1 = bridge.getLight(1);
+hueplusplus::HueLight light1 = bridge.lights().get(1);
 ```
 If you don't know the id of a specific light or want to get an overview over all lights that are controlled by your bridge, 
-you can get a vector containing them by calling [getAllLights()](@ref hueplusplus::Hue::getAllLights) on your bridge object. If no lights are found the vector will be empty.
+you can get a vector containing them by calling [getAll()](@ref hueplusplus::ResourceList::getAll) on your bridge object. If no lights are found the vector will be empty.
 ```{.cpp}
-std::vector<std::reference_wrapper<hueplusplus::HueLight>> lights = bridge.getAllLights();
+std::vector<std::reference_wrapper<hueplusplus::HueLight>> lights = bridge.lights().getAll();
 ```
 If you now want to control a light, call a specific function of it.
 ```{.cpp}
@@ -151,11 +151,13 @@ public:
     Hue(const std::string& ip, const int port, const std::string& username, std::shared_ptr<const IHttpHandler> handler,
         std::chrono::steady_clock::duration refreshDuration = std::chrono::seconds(10));
  
+    //! \brief Refreshes the bridge state.
+    //!
+    //! Should only be called rarely, as a full refresh is costly and usually not necessary.
+    //! Instead refresh only the parts you are interested in or rely on periodic refreshes
+    //! that happen automatically when calling non-const methods.
     void refresh();
  
-    //! \name Configuration
-    ///@{
-
     //! \brief Function to get the ip address of the hue bridge
     //!
     //! \return string containing ip
@@ -193,28 +195,46 @@ public:
     //! "192.168.2.1:8080"
     void setPort(const int port);
  
-    //! \brief Function that sets the HttpHandler and updates the HueCommandAPI.
-    //!
-    //! The HttpHandler and HueCommandAPI are used for bridge communication
-    //! \param handler a HttpHandler of type \ref IHttpHandler
-    void setHttpHandler(std::shared_ptr<const IHttpHandler> handler);
-
+    //! \brief Provides access to the configuration of the bridge.
     BridgeConfig& config();
+    //! \brief Provides access to the configuration of the bridge.
+    //! \note Does not refresh state.
     const BridgeConfig& config() const;
-
+    
+    //! \brief Provides access to the HueLight%s on the bridge.
     LightList& lights();
+    //! \brief Provides access to the HueLight%s on the bridge.
+    //! \note Does not refresh state.
     const LightList& lights() const;
  
+    //! \brief Provides access to the Group%s on the bridge.
     GroupList& groups();
+    //! \brief Provides access to the Group%s on the bridge.
+    //! \note Does not refresh state.
     const GroupList& groups() const;
  
+    //! \brief Provides access to the Schedule%s on the bridge.
     ScheduleList& schedules();
+    //! \brief Provides access to the Schedule%s on the bridge.
+    //! \note Does not refresh state.
     const ScheduleList& schedules() const;
  
+    //! \brief Provides access to the Scene%s on the bridge.
     SceneList& scenes();
+    //! \brief Provides access to the Scene%s on the bridge.
+    //! \note Does not refresh state.
     const SceneList& scenes() const;
  
 private:
+    //! \brief Function that sets the HttpHandler and updates the HueCommandAPI.
+    //! \param handler a HttpHandler of type \ref IHttpHandler
+    //!
+    //! The HttpHandler and HueCommandAPI are used for bridge communication.
+    //! Resetting the HttpHandler should only be done when the username is first set,
+    //! before Hue is used.
+    //! Resets all caches and resource lists.
+    void setHttpHandler(std::shared_ptr<const IHttpHandler> handler);
+private:
     std::string ip; //!< IP-Address of the hue bridge in dotted decimal notation
                     //!< like "192.168.2.1"
     std::string username; //!< Username that is ussed to access the hue bridge