service call doc updates

docs/HASS_API_REFERENCE.rst

@@ -393,16 +393,60 @@ Here's one example
 
 
     class MyApp(Hass):
-        def initialize(self):
+        def initialize(self) -> None:
             self.call_service(
                 "notify/alexa_media",
                 service_data={
                     "target": "media_player.tom_office",
                     "data": {"type": "announce"}
-                }
+                },
+                # other kwargs also will be included in service_data
                 message="This is a test message"
             )
 
+.. code-block:: JSON
+
+    // JSON sent to Home Assistant over websocket API
+    {
+        "type": "call_service",
+        "domain": "notify",
+        "service": "alexa_media",
+        "service_data": {
+            "target": "media_player.tom_office",
+            "data": {
+                "type": "announce"
+            },
+            "message": "This is a test message"
+        },
+        "id": 7 // This ID is generated by AppDaemon and is used to match the response whenever it arrives
+    }
+
+The kwarg ``target`` can't be used directly because it would conflict with ``target`` being used in other services, like
+this:
+
+.. code-block:: python
+
+    from appdaemon.plugins.hass import Hass
+
+
+    class SimpleApp(Hass):
+        def initialize(self) -> None:
+            self.call_service("light/turn_on", target="light.kitchen", brightness=255)
+
+.. code-block:: JSON
+
+    // JSON sent to Home Assistant over websocket API
+    {
+        "type": "call_service",
+        "domain": "light",
+        "service": "turn_on",
+        "service_data": {
+            "brightness": 255
+        },
+        "target": "light.kitchen",
+        "id": 7 // This ID is generated by AppDaemon and is used to match the response whenever it arrives
+    }
+
 Debugging
 ^^^^^^^^^
 
@@ -455,6 +499,18 @@ internally. This contains a little more detail than is visible in the Home Assis
 
 Turning up the logging level to ``DEBUG`` to inspect the raw JSON being sent over the websocket.
 
+.. code-block:: YAML
+
+    # conf/appdaemon.yaml
+    appdaemon:
+      ...             # rest of AppDaemon config here
+      module_debug:
+        HASS: DEBUG   # This must match the name of the plugin
+      plugins:
+        HASS:         # This is the name of the plugin, which can be changed
+          type: hass  # This must be exactly "hass"
+          ...         # rest of Hass plugin config here
+
 Error Handling
 ^^^^^^^^^^^^^^
 
@@ -493,7 +549,7 @@ a per-call basis you can set the ``suppress_log_messages`` argument to ``True``
 setting ``suppress_log_messages`` to true in the plugin configuration.
 
 .. code-block:: python
-  :emphasize-lines: 10
+  :emphasize-lines: 11
 
     from appdaemon.plugins.hass import Hass