From 0660f3b349e55db4b7fda82190dd04edf1698497 Mon Sep 17 00:00:00 2001
From: Martin Eberhardt <martin@darkfox.dk>
Date: Thu, 14 Feb 2019 10:16:12 +0100
Subject: [PATCH] Improve mqtt.publish service documentation (#8562)

Current documentation doesn't mention the qos or retain attributes.
---
 source/_docs/mqtt/service.markdown | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/source/_docs/mqtt/service.markdown b/source/_docs/mqtt/service.markdown
index d4a7aad206d..223d554d3f9 100644
--- a/source/_docs/mqtt/service.markdown
+++ b/source/_docs/mqtt/service.markdown
@@ -12,6 +12,20 @@ logo: mqtt.png
 
 The MQTT component will register the service `mqtt.publish` which allows publishing messages to MQTT topics. There are two ways of specifying your payload. You can either use `payload` to hard-code a payload or use `payload_template` to specify a [template](/topics/templating/) that will be rendered to generate the payload.
 
+### {% linkable_title Service `mqtt.publish` %}
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `topic` | no | Topic to publish payload to.
+| `payload` | yes | Payload to publish.
+| `payload_template` | yes | Template to render as payload value. Ignored if payload given.
+| `qos` | yes | Quality of Service to use.
+| `retain` | yes | If message should have the retain flag set. (default: false)
+
+<p class='note'>
+You need to include either payload or payload_template, but not both.
+</p>
+
 ```json
 {
   "topic": "home-assistant/light/1/command",
@@ -36,3 +50,14 @@ The MQTT component will register the service `mqtt.publish` which allows publish
   "payload":"{\"Status\":\"off\", \"Data\":\"something\"}"
 }
 ``` 
+
+Example of how to use `qos` and `retain`:
+
+```json
+{
+  "topic": "home-assistant/light/1/command",
+  "payload": "on",
+  "qos": 2,
+  "retain": true
+}
+```