docs(schema): Add documentation for connector records

apps/emqx_connector/src/mqtt/emqx_connector_mqtt_schema.erl

@@ -22,6 +22,7 @@
 
 -export([ roots/0
         , fields/1
+        , desc/1
         ]).
 
 -export([ ingress_desc/0
@@ -43,19 +44,19 @@ fields("connector") ->
     [ {mode,
         sc(hoconsc:enum([cluster_shareload]),
            #{ default => cluster_shareload
-            , desc => """
+            , desc => "
-The mode of the MQTT Bridge. Can be one of 'cluster_singleton' or 'cluster_shareload'<br>
+The mode of the MQTT Bridge. Can be one of 'cluster_singleton' or 'cluster_shareload'<br/>
 
-- cluster_singleton: create a unique MQTT connection within the emqx cluster.<br>
+- cluster_singleton: create a unique MQTT connection within the emqx cluster.<br/>
 In 'cluster_singleton' node, all messages toward the remote broker go through the same
-MQTT connection.<br>
+MQTT connection.<br/>
-- cluster_shareload: create an MQTT connection on each node in the emqx cluster.<br>
+- cluster_shareload: create an MQTT connection on each node in the emqx cluster.<br/>
 In 'cluster_shareload' mode, the incoming load from the remote broker is shared by
-using shared subscription.<br>
+using shared subscription.<br/>
 Note that the 'clientid' is suffixed by the node name, this is to avoid
 clientid conflicts between different nodes. And we can only use shared subscription
 topic filters for 'remote_topic' of ingress connections.
-"""
+"
             })}
     , {server,
         sc(emqx_schema:ip_port(),
@@ -97,11 +98,7 @@ topic filters for 'remote_topic' of ingress connections.
             , desc => "Max inflight (sent, but un-acked) messages of the MQTT protocol"
             })}
     , {replayq,
-        sc(ref("replayq"),
+        sc(ref("replayq"), #{})}
-           #{ desc => """
-Queue messages in disk files.
-"""
-            })}
     ] ++ emqx_connector_schema_lib:ssl_fields();
 
 fields("ingress") ->
@@ -120,23 +117,23 @@ fields("ingress") ->
     , {local_topic,
         sc(binary(),
            #{ validator => fun ?MODULE:non_empty_string/1
-            , desc => """
+            , desc => "
-Send messages to which topic of the local broker.<br>
+Send messages to which topic of the local broker.<br/>
 Template with variables is allowed.
-"""
+"
             })}
     , {local_qos,
         sc(qos(),
            #{ default => <<"${qos}">>
-            , desc => """
+            , desc => "
-The QoS of the MQTT message to be sent.<br>
+The QoS of the MQTT message to be sent.<br/>
-Template with variables is allowed."""
+Template with variables is allowed."
             })}
     , {hookpoint,
         sc(binary(),
-           #{ desc => """
+           #{ desc => "
 The hook point will be triggered when there's any message received from the remote broker.
-"""
+"
             })}
     ] ++ common_inout_confs();
 
@@ -151,94 +148,101 @@ fields("egress") ->
         sc(binary(),
            #{ default => <<"${topic}">>
             , validator => fun ?MODULE:non_empty_string/1
-            , desc => """
+            , desc => "
-Forward to which topic of the remote broker.<br>
+Forward to which topic of the remote broker.<br/>
 Template with variables is allowed.
-"""
+"
             })}
     , {remote_qos,
         sc(qos(),
            #{ default => <<"${qos}">>
-            , desc => """
+            , desc => "
-The QoS of the MQTT message to be sent.<br>
+The QoS of the MQTT message to be sent.<br/>
-Template with variables is allowed."""
+Template with variables is allowed."
             })}
     ] ++ common_inout_confs();
 
 fields("replayq") ->
     [ {dir,
         sc(hoconsc:union([boolean(), string()]),
-           #{ desc => """
+           #{ desc => "
-The dir where the replayq file saved.<br>
+The dir where the replayq file saved.<br/>
 Set to 'false' disables the replayq feature.
-"""
+"
             })}
     , {seg_bytes,
         sc(emqx_schema:bytesize(),
            #{ default => "100MB"
-            , desc => """
+            , desc => "
-The size in bytes of a single segment.<br>
+The size in bytes of a single segment.<br/>
 A segment is mapping to a file in the replayq dir. If the current segment is full, a new segment
 (file) will be opened to write.
-"""
+"
             })}
     , {offload,
         sc(boolean(),
            #{ default => false
-            , desc => """
+            , desc => "
-In offload mode, the disk queue is only used to offload queue tail segments.<br>
+In offload mode, the disk queue is only used to offload queue tail segments.<br/>
 The messages are cached in the memory first, then it writes to the replayq files after the size of
 the memory cache reaches 'seg_bytes'.
-"""
+"
             })}
     ].
 
+desc("ingress") ->
+    ingress_desc();
+desc("egress") ->
+    egress_desc();
+desc("replayq") ->
+    "Queue messages in disk files.";
+desc(_) ->
+    undefined.
+
 topic_mappings() ->
     [ {ingress,
         sc(ref("ingress"),
            #{ default => #{}
-            , desc => ingress_desc()
             })}
     , {egress,
         sc(ref("egress"),
            #{ default => #{}
-            , desc => egress_desc()
             })}
     ].
 
-ingress_desc() -> """
+ingress_desc() -> "
 The ingress config defines how this bridge receive messages from the remote MQTT broker, and then
-send them to the local broker.<br>
+send them to the local broker.<br/>
 Template with variables is allowed in 'local_topic', 'remote_qos', 'qos', 'retain',
-'payload'.<br>
+'payload'.<br/>
 NOTE: if this bridge is used as the input of a rule (emqx rule engine), and also local_topic is
 configured, then messages got from the remote broker will be sent to both the 'local_topic' and
 the rule.
-""".
+".
 
-egress_desc() -> """
+egress_desc() -> "
 The egress config defines how this bridge forwards messages from the local broker to the remote
-broker.<br>
+broker.<br/>
-Template with variables is allowed in 'remote_topic', 'qos', 'retain', 'payload'.<br>
+Template with variables is allowed in 'remote_topic', 'qos', 'retain', 'payload'.<br/>
 NOTE: if this bridge is used as the output of a rule (emqx rule engine), and also local_topic
 is configured, then both the data got from the rule and the MQTT messages that matches
 local_topic will be forwarded.
-""".
+".
 
 common_inout_confs() ->
     [ {retain,
         sc(hoconsc:union([boolean(), binary()]),
            #{ default => <<"${retain}">>
-            , desc => """
+            , desc => "
-The 'retain' flag of the MQTT message to be sent.<br>
+The 'retain' flag of the MQTT message to be sent.<br/>
-Template with variables is allowed."""
+Template with variables is allowed."
             })}
     , {payload,
         sc(binary(),
            #{ default => <<"${payload}">>
-            , desc => """
+            , desc => "
-The payload of the MQTT message to be sent.<br>
+The payload of the MQTT message to be sent.<br/>
-Template with variables is allowed."""
+Template with variables is allowed."
             })}
     ].