From 3cd4eb1003341d6e873b3dbec31ae70f54417871 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Tue, 24 Aug 2021 12:44:36 +0200
Subject: [PATCH] Adjust homeassistant services description to clarify their
 purpose (#19035)

---
 source/_integrations/homeassistant.markdown | 35 +++++++++++++++------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/source/_integrations/homeassistant.markdown b/source/_integrations/homeassistant.markdown
index ef0270e522a..fccd2f0e54b 100644
--- a/source/_integrations/homeassistant.markdown
+++ b/source/_integrations/homeassistant.markdown
@@ -38,7 +38,7 @@ Reloads the core configuration under `homeassistant:` and all linked files. Once
 
 ### Service `homeassistant.restart`
 
-Restarts the Home Assistant instance (also reloading the configuration on start). 
+Restarts the Home Assistant instance (also reloading the configuration on start).
 
 This will also do a configuration check before doing a restart. If the configuration check fails then Home Assistant will not be restarted, instead a persistent notification with the ID `persistent_notification.homeassistant_check_config` will be created. The logs will show details on what failed the configuration check.
 
@@ -65,9 +65,12 @@ action:
     longitude: 117.22743
 ```
 
-### Service `homeassistant.toggle` 
+### Service `homeassistant.toggle`
 
-Generic service to toggle devices on/off under any domain. Same usage as the light.turn_on, switch.turn_on, etc. services.
+Generic service to toggle devices on/off. Same usage as the
+`light.toggle`, `switch.toggle`, etc. services. The difference with this
+service compared the others, is that is can be used to mix different domains,
+for example, a light and a switch can be toggled in a single service call.
 
 | Service data attribute    | Optional | Description                                           |
 |---------------------------|----------|-------------------------------------------------------|
@@ -79,12 +82,17 @@ Generic service to toggle devices on/off under any domain. Same usage as the lig
 action:
   service: homeassistant.toggle
   target:
-    entity_id: light.living_room
+    entity_id: 
+      - light.living_room
+      - switch.tv
 ```
 
-### Service `homeassistant.turn_on` 
+### Service `homeassistant.turn_on`
 
-Generic service to turn devices on under any domain. Same usage as the light.turn_on, switch.turn_on, etc. services.
+Generic service to toggle devices on. Same usage as the
+`light.turn_on`, `switch.turn_on`, etc. services. The difference with this
+service compared the others, is that is can be used to mix different domains,
+for example, a light and a switch can be turned on in a single service call.
 
 | Service data attribute    | Optional | Description                                           |
 |---------------------------|----------|-------------------------------------------------------|
@@ -96,12 +104,17 @@ Generic service to turn devices on under any domain. Same usage as the light.tur
 action:
   service: homeassistant.turn_on
   target:
-    entity_id: light.living_room
+    entity_id:
+      - light.living_room
+      - switch.tv
 ```
 
 ### Service `homeassistant.turn_off` 
 
-Generic service to turn devices off under any domain. Same usage as the light.turn_on, switch.turn_on, etc. services.
+Generic service to toggle devices off. Same usage as the
+`light.turn_off`, `switch.turn_off`, etc. services. The difference with this
+service compared the others, is that is can be used to mix different domains,
+for example, a light and a switch can be turned off in a single service call.
 
 | Service data attribute    | Optional | Description                                           |
 |---------------------------|----------|-------------------------------------------------------|
@@ -113,10 +126,12 @@ Generic service to turn devices off under any domain. Same usage as the light.tu
 action:
   service: homeassistant.turn_off
   target:
-    entity_id: light.living_room
+    entity_id:
+      - light.living_room
+      - switch.tv
 ```
 
-### Service `homeassistant.update_entity` 
+### Service `homeassistant.update_entity`
 
 Force one or more entities to update its data rather than wait for the next scheduled update.