From d8e16b37dac1a52f1e9dfe3f9c274300489a1012 Mon Sep 17 00:00:00 2001
From: ieQu1 <99872536+ieQu1@users.noreply.github.com>
Date: Wed, 30 Mar 2022 09:55:32 +0200
Subject: [PATCH] docs(schema): Add documentation for the fields and records

---
 .../emqx_limiter/src/emqx_limiter_schema.erl  | 13 ++++++-
 apps/emqx/src/emqx_schema.erl                 |  8 ++++-
 apps/emqx_gateway/src/emqx_gateway_schema.erl | 34 ++++++++++++-------
 apps/emqx_modules/src/emqx_modules_schema.erl | 14 +++++++-
 4 files changed, 54 insertions(+), 15 deletions(-)

diff --git a/apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl b/apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl
index 498f862e0..7ae4a01cc 100644
--- a/apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl
+++ b/apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl
@@ -20,7 +20,7 @@
 
 -export([ roots/0, fields/1, to_rate/1, to_capacity/1
         , minimum_period/0, to_burst_rate/1, to_initial/1
-        , namespace/0, get_bucket_cfg_path/2
+        , namespace/0, get_bucket_cfg_path/2, desc/1
         ]).
 
 -define(KILOBYTE, 1024).
@@ -149,6 +149,17 @@ the check/consume will succeed, but it will be forced to wait for a short period
                              , default => force})}
     ].
 
+desc(limiter) ->
+    "Settings for the rate limiter.";
+desc(limiter_opts) ->
+    "Settings for the limiter.";
+desc(bucket_opts) ->
+    "Settings for the bucket.";
+desc(client_bucket) ->
+    "Settings for the client bucket.";
+desc(_) ->
+    undefined.
+
 %% minimum period is 100ms
 minimum_period() ->
     100.
diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl
index 614838ce0..072603b1e 100644
--- a/apps/emqx/src/emqx_schema.erl
+++ b/apps/emqx/src/emqx_schema.erl
@@ -1715,7 +1715,13 @@ base_listener() ->
                 }
             )},
         {"limiter",
-            sc(map("ratelimit's type", emqx_limiter_schema:bucket_name()), #{default => #{}})}
+            sc(
+                map("ratelimit's type", emqx_limiter_schema:bucket_name()),
+                #{
+                    default => #{},
+                    desc => "Type of the rate limit."
+                }
+            )}
     ].
 
 desc("persistent_session_store") ->
diff --git a/apps/emqx_gateway/src/emqx_gateway_schema.erl b/apps/emqx_gateway/src/emqx_gateway_schema.erl
index d3d207c04..b1828559d 100644
--- a/apps/emqx_gateway/src/emqx_gateway_schema.erl
+++ b/apps/emqx_gateway/src/emqx_gateway_schema.erl
@@ -294,18 +294,22 @@ fields(exproto) ->
 fields(exproto_grpc_server) ->
     [ {bind,
        sc(hoconsc:union([ip_port(), integer()]),
-          #{required => true})}
+          #{ required => true
+           , desc => "Listening address and port for the gRPC server."
+           })}
     , {ssl,
        sc(ref(ssl_server_opts),
           #{ required => {false, recursively}
+           , desc => "SSL configuration for the gRPC server."
            })}
     ];
 
 fields(exproto_grpc_handler) ->
-    [ {address, sc(binary(), #{required => true})}
+    [ {address, sc(binary(), #{required => true, desc => "gRPC server address."})}
     , {ssl,
        sc(ref(emqx_schema, ssl_client_opts),
           #{ required => {false, recursively}
+           , desc => "SSL configuration for the gRPC client."
            })}
     ];
 
@@ -362,25 +366,31 @@ the LwM2M client"
     ];
 
 fields(translator) ->
-    [ {topic, sc(binary(), #{required => true})}
-    , {qos, sc(emqx_schema:qos(), #{default => 0})}
+    [ {topic, sc(binary(),
+                 #{ required => true
+                  , desc => "Which topic the device's upstream message is published to."
+                  })}
+    , {qos, sc(emqx_schema:qos(),
+               #{ default => 0
+                , desc => "QoS of the published messages."
+                })}
     ];
 
 fields(udp_listeners) ->
-    [ {udp, sc(map(name, ref(udp_listener)))}
-    , {dtls, sc(map(name, ref(dtls_listener)))}
+    [ {udp, sc(map(name, ref(udp_listener)), #{desc => "UDP configuration."})}
+    , {dtls, sc(map(name, ref(dtls_listener)), #{desc => "DTLS configuration."})}
     ];
 
 fields(tcp_listeners) ->
-    [ {tcp, sc(map(name, ref(tcp_listener)))}
-    , {ssl, sc(map(name, ref(ssl_listener)))}
+    [ {tcp, sc(map(name, ref(tcp_listener)), #{desc => "TCP configuration."})}
+    , {ssl, sc(map(name, ref(ssl_listener)), #{desc => "SSL configuration."})}
     ];
 
 fields(udp_tcp_listeners) ->
-    [ {udp, sc(map(name, ref(udp_listener)))}
-    , {dtls, sc(map(name, ref(dtls_listener)))}
-    , {tcp, sc(map(name, ref(tcp_listener)))}
-    , {ssl, sc(map(name, ref(ssl_listener)))}
+    [ {udp, sc(map(name, ref(udp_listener)), #{desc => "UDP configuration."})}
+    , {dtls, sc(map(name, ref(dtls_listener)), #{desc => "DTLS configuration."})}
+    , {tcp, sc(map(name, ref(tcp_listener)), #{desc => "TCP configuration."})}
+    , {ssl, sc(map(name, ref(ssl_listener)), #{desc => "SSL configuration."})}
     ];
 
 fields(tcp_listener) ->
diff --git a/apps/emqx_modules/src/emqx_modules_schema.erl b/apps/emqx_modules/src/emqx_modules_schema.erl
index 4b27879e2..4fa623dd2 100644
--- a/apps/emqx_modules/src/emqx_modules_schema.erl
+++ b/apps/emqx_modules/src/emqx_modules_schema.erl
@@ -23,7 +23,8 @@
 -export([
     namespace/0,
     roots/0,
-    fields/1
+    fields/1,
+    desc/1
 ]).
 
 namespace() -> modules.
@@ -65,6 +66,17 @@ fields("rewrite") ->
 fields("topic_metrics") ->
     [{topic, sc(binary(), #{})}].
 
+desc("telemetry") ->
+    "Settings for the telemetry module.";
+desc("delayed") ->
+    "Settings for the delayed module.";
+desc("rewrite") ->
+    "Settings for the rewrite module.";
+desc("topic_metrics") ->
+    "Settings for the topic metrics module.";
+desc(_) ->
+    undefined.
+
 regular_expression(type) -> binary();
 regular_expression(desc) -> "Regular expressions";
 regular_expression(example) -> "^x/y/(.+)$";