Merge pull request #1439 from Odianosen25/dev

appdaemon/entity.py

@@ -234,10 +234,6 @@ async def listen_state(self, callback: Callable, **kwargs: Optional[Any]) -> str
 
             >>> self.handle = self.my_enitity.listen_state(self.my_callback)
 
-            Listen for a state change involving `light.office1` and return the entire state as a dict.
-
-            >>> self.handle = self.my_enitity.listen_state(self.my_callback, attribute = "all")
-
             Listen for a change involving the brightness attribute of `light.office1` and return the
             brightness attribute.
 
@@ -275,8 +271,27 @@ async def listen_state(self, callback: Callable, **kwargs: Optional[Any]) -> str
         return await self.AD.state.add_state_callback(name, namespace, entity_id, callback, kwargs)
 
     @utils.sync_wrapper
-    async def add(self, state: str = None, attributes: dict = None) -> None:
-        """Adds a non-existent entity, by creating it within a namespaces."""
+    async def add(self, state: Union[str, int, float] = None, attributes: dict = None) -> None:
+        """Adds a non-existent entity, by creating it within a namespaces.
+
+        It should be noted that this api call, is mainly for creating AD internal entities.
+        If wanting to create an entity within an external system, do check the system's documentation
+
+        Args:
+            state (optional): The state the new entity is to have
+            attributes (optional): The attributes the new entity is to have
+
+        Returns:
+            None
+
+        Examples:
+            >>> self.my_enitity = self.get_entity("zigbee.living_room_light")
+
+            create the entity entity.
+
+            >>> self.my_enitity.add(state="off", attributes={"friendly_name": "Living Room Light"})
+
+        """
 
         namespace = self._namespace
         entity_id = self._entity_id
@@ -428,15 +443,25 @@ async def copy(self, copy: bool = True) -> dict:
         This is essentially a helper function, to get all data about an entity
 
         Args:
-            copy(bool): If set to False, it will not make a deep copy of the entity.
-            This can help with speed of accessing the data
+            copy (bool): If set to False, it will not make a deep copy of the entity. This can help with speed of accessing the data
         """
 
         return await self.get_state(attribute="all", copy=copy, default={})
 
     @utils.sync_wrapper
     async def is_state(self, state: Any) -> bool:
-        """Checks the state of the entity against the given state"""
+        """Checks the state of the entity against the given state
+
+        This helper function supports using both iterable and non-iterable data
+
+        Args:
+            state (any): The state or iterable set of state data, to check against
+
+        Example:
+            >>> light_entity_object.is_state("on")
+            >>> media_object.is_state(["playing", "paused"])
+
+        """
 
         entity_state = await self.get_state(copy=False)
 
@@ -450,19 +475,43 @@ async def is_state(self, state: Any) -> bool:
 
     @utils.sync_wrapper
     async def turn_on(self, **kwargs: Optional[Any]) -> Any:
-        """Generic function, used to turn the entity ON if supported"""
+        """Generic function, used to turn the entity ON if supported
+
+        Keyword Args:
+            **kwargs: Turn_on services depending on the namespace functioning within
+                has different parameter requirements. This argument
+                allows you to specify a comma-separated list of keyword value pairs, e.g.,
+                `transition = 3`. These parameters will be different for
+                every service being used.
+        """
 
         return await self.call_service("turn_on", **kwargs)
 
     @utils.sync_wrapper
     async def turn_off(self, **kwargs: Optional[Any]) -> Any:
-        """Generic function, used to turn the entity OFF if supported"""
+        """Generic function, used to turn the entity OFF if supported
+
+        Keyword Args:
+            **kwargs: Turn_off services depending on the namespace functioning within
+                has different parameter requirements. This argument
+                allows you to specify a comma-separated list of keyword value pairs, e.g.,
+                `transition = 3`. These parameters will be different for
+                every service being used.
+        """
 
         return await self.call_service("turn_off", **kwargs)
 
     @utils.sync_wrapper
     async def toggle(self, **kwargs: Optional[Any]) -> Any:
-        """Generic function, used to toggle the entity ON/OFF if supported"""
+        """Generic function, used to toggle the entity ON/OFF if supported
+
+        Keyword Args:
+            **kwargs: Toggle services depending on the namespace functioning within
+                has different parameter requirements. This argument
+                allows you to specify a comma-separated list of keyword value pairs, e.g.,
+                `transition = 3`. These parameters will be different for
+                every service being used.
+        """
 
         return await self.call_service("toggle", **kwargs)