From ad12c3a4e369e1f601f47b249fc4be2e68a2b6e6 Mon Sep 17 00:00:00 2001
From: DDDHuang <44492639+DDDHuang@users.noreply.github.com>
Date: Thu, 24 Mar 2022 10:02:59 +0800
Subject: [PATCH] fix(doc): add auto sub docs & more notes

---
 .../etc/emqx_auto_subscribe.conf              | 17 +++++++++++++++
 .../src/emqx_auto_subscribe_schema.erl        | 21 ++++++++++++++-----
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/apps/emqx_auto_subscribe/etc/emqx_auto_subscribe.conf b/apps/emqx_auto_subscribe/etc/emqx_auto_subscribe.conf
index becc87516..a12b30fa1 100644
--- a/apps/emqx_auto_subscribe/etc/emqx_auto_subscribe.conf
+++ b/apps/emqx_auto_subscribe/etc/emqx_auto_subscribe.conf
@@ -1,4 +1,21 @@
 
+## When the device log in successfully,
+## The auto-subscribe will complete the subscription for the device
+## according to the preset topics list.
+## Placeholders is supported.
+##
+## - ${clientid}
+## - ${username}
+## - ${host}
+## - ${port}
+##
+## Subscription options can be set at the same time.
+## Please refer to the official MQTT definition for these configuration items.
+## - qos
+## - rh
+## - rap
+## - nl
+##
 auto_subscribe {
     topics = [
         ## {
diff --git a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl
index 917030266..7c034a8af 100644
--- a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl
+++ b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl
@@ -34,11 +34,22 @@ fields("auto_subscribe") ->
     ];
 
 fields("topic") ->
-    [ {topic, sc(binary(), #{example => topic_example()})}
-    , {qos, sc(emqx_schema:qos(), #{default => 0})}
-    , {rh, sc(range(0,2), #{default => 0})}
-    , {rap, sc(range(0, 1), #{default => 0})}
-    , {nl, sc(range(0, 1), #{default => 0})}
+    [ {topic, sc(binary(), #{
+        example => topic_example(),
+        desc => "Topic name, placeholders is supported. For example: "
+                ++ binary_to_list(topic_example())})}
+    , {qos, sc(emqx_schema:qos(), #{
+        default => 0,
+        desc => "Quality of service. MQTT definition."})}
+    , {rh, sc(range(0,2), #{
+        default => 0,
+        desc => "Retain handling. MQTT 5.0 definition."})}
+    , {rap, sc(range(0, 1), #{
+        default => 0,
+        desc => "Retain as Published. MQTT 5.0 definition."})}
+    , {nl, sc(range(0, 1), #{
+        default => 0,
+        desc => "Not local. MQTT 5.0 definition."})}
     ].
 
 topic_example() ->