From b79ef3f0d9e88fd7be2e48774658d802bf9494a2 Mon Sep 17 00:00:00 2001
From: ieQu1 <99872536+ieQu1@users.noreply.github.com>
Date: Tue, 22 Feb 2022 12:56:57 +0100
Subject: [PATCH] docs: Add documentation for the cluster

---
 apps/emqx_conf/src/emqx_conf_schema.erl | 73 +++++++++++++++++++------
 scripts/spellcheck                      |  2 +-
 2 files changed, 57 insertions(+), 18 deletions(-)

diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl
index aa8c64bf1..11afd497c 100644
--- a/apps/emqx_conf/src/emqx_conf_schema.erl
+++ b/apps/emqx_conf/src/emqx_conf_schema.erl
@@ -112,47 +112,58 @@ fields("cluster") ->
        sc(atom(),
           #{ mapping => "ekka.cluster_name"
            , default => emqxcl
+           , desc => "Human-friendly name of the EMQX cluster."
            })}
     , {"discovery_strategy",
        sc(hoconsc:enum([manual, static, mcast, dns, etcd, k8s]),
           #{ default => manual
+           , desc => "Service discovery method for the cluster nodes."
            })}
     , {"autoclean",
        sc(emqx_schema:duration(),
           #{ mapping => "ekka.cluster_autoclean"
            , default => "5m"
+           , desc => "Remove disconnected nodes from the cluster after this interval."
            })}
     , {"autoheal",
        sc(boolean(),
           #{ mapping => "ekka.cluster_autoheal"
            , default => true
+           , desc => "If <code>true</code>, the node will try to heal network partitions automatically."
            })}
-    , {"static",
-       sc(ref(cluster_static),
-          #{})}
-    , {"mcast",
-       sc(ref(cluster_mcast),
-          #{})}
     , {"proto_dist",
        sc(hoconsc:enum([inet_tcp, inet6_tcp, inet_tls]),
           #{ mapping => "ekka.proto_dist"
            , default => inet_tcp
            })}
+    , {"static",
+       sc(ref(cluster_static),
+          #{ desc => "Static service discovery mechanism, when all the nodes are known
+ in advance."
+           })}
+    , {"mcast",
+       sc(ref(cluster_mcast),
+          #{ desc => "Service discovery via UDP multicast."
+           })}
     , {"dns",
        sc(ref(cluster_dns),
-          #{})}
+          #{ desc => "Service discovery via DNS SRV records."
+           })}
     , {"etcd",
        sc(ref(cluster_etcd),
-          #{})}
+          #{ desc => "Service discovery using 'etcd' service."
+           })}
     , {"k8s",
        sc(ref(cluster_k8s),
-          #{})}
+          #{ desc => "Service discovery via Kubernetes API server."
+           })}
     ];
 
 fields(cluster_static) ->
     [ {"seeds",
       sc(hoconsc:array(atom()),
          #{ default => []
+          , desc => "List EMQX node names in the static cluster. See <code>node.name</code>."
           })}
     ];
 
@@ -160,34 +171,43 @@ fields(cluster_mcast) ->
     [ {"addr",
        sc(string(),
           #{ default => "239.192.0.1"
+           , desc => "Multicast IPv4 address."
            })}
     , {"ports",
        sc(hoconsc:array(integer()),
           #{ default => [4369, 4370]
+           , desc => "List of UDP ports used for service discovery.<br/>
+Note: probe messages are broadcasted to all the specified ports."
            })}
     , {"iface",
        sc(string(),
           #{ default => "0.0.0.0"
+           , desc => "IPv4 interface address."
            })}
     , {"ttl",
        sc(range(0, 255),
           #{ default => 255
+           , desc => "Time-to-live (TTL) for the outgoing UDP datagrams."
            })}
     , {"loop",
        sc(boolean(),
           #{ default => true
+           , desc => "If <code>true</code>, loop UDP datagrams back to the local socket."
            })}
     , {"sndbuf",
        sc(emqx_schema:bytesize(),
           #{ default => "16KB"
+           , desc => "Size of the kernel-level buffer for outgoing datagrams."
            })}
     , {"recbuf",
        sc(emqx_schema:bytesize(),
           #{ default => "16KB"
+           , desc => "Size of the kernel-level buffer for incoming datagrams."
            })}
     , {"buffer",
        sc(emqx_schema:bytesize(),
           #{ default =>"32KB"
+           , desc => "Size of the user-level buffer."
            })}
     ];
 
@@ -195,52 +215,70 @@ fields(cluster_dns) ->
     [ {"name",
        sc(string(),
           #{ default => "localhost"
+           , desc => "The domain name of the EMQX cluster."
            })}
     , {"app",
        sc(string(),
           #{ default => "emqx"
+           , desc => "The symbolic name of the EMQX service."
            })}
     ];
 
 fields(cluster_etcd) ->
     [ {"server",
        sc(emqx_schema:comma_separated_list(),
-          #{})}
+          #{ desc => "List of endpoint URLs of the etcd cluster"
+           })}
     , {"prefix",
        sc(string(),
           #{ default => "emqxcl"
+           , desc => "Key prefix used for EMQX service discovery."
            })}
     , {"node_ttl",
        sc(emqx_schema:duration(),
           #{ default => "1m"
+           , desc => "Expiration time of the etcd key associated with the node.
+It is refreshed automatically, as long as the node is alive."
            })}
     , {"ssl",
        sc(hoconsc:ref(emqx_schema, ssl_client_opts),
-          #{})}
+          #{ desc => "Options for the TLS connection to the etcd cluster."
+           })}
     ];
 
 fields(cluster_k8s) ->
     [ {"apiserver",
        sc(string(),
-          #{})}
+          #{ desc => "Kubernetes API endpoint URL."
+           })}
     , {"service_name",
        sc(string(),
           #{ default => "emqx"
+           , desc => "EMQX service name."
            })}
     , {"address_type",
        sc(hoconsc:enum([ip, dns, hostname]),
-          #{})}
+          #{ desc => "Address type used for connecting to the discovered nodes."
+           })}
     , {"app_name",
        sc(string(),
           #{ default => "emqx"
+           , desc => "This parameter should be set to the part of the <code>node.name</code>
+before the '@'.<br/>
+For example, if the <code>node.name</code> is <code>emqx@127.0.0.1</code>, then this parameter
+should be set to <code>emqx</code>."
            })}
     , {"namespace",
        sc(string(),
           #{ default => "default"
+           , desc => "Kubernetes namespace."
            })}
     , {"suffix",
        sc(string(),
-          #{default => "pod.local"
+          #{ default => "pod.local"
+           , desc => "Node name suffix.<br/>
+Note: this parameter is only relevant when <code>address_type</code> is <code>dns</code>
+or <code>hostname</code>."
            })}
     ];
 
@@ -249,7 +287,7 @@ fields("node") ->
        sc(string(),
           #{ default => "emqx@127.0.0.1",
              desc => "Unique name of the EMQX node. It must follow <code>%name%@FQDN</code> or
- <code>%name%@IP</code> format."
+ <code>%name%@IPv4</code> format."
            })}
     , {"cookie",
        sc(string(),
@@ -353,7 +391,8 @@ a crash dump"
          )}
     , {"cluster_call",
       sc(ref("cluster_call"),
-        #{
+        #{ desc => "Options for the 'cluster call' feature that allows to execute a callback
+ on all nodes in the cluster."
           }
         )}
     ];
@@ -432,7 +471,7 @@ fields("cluster_call") ->
        sc(emqx_schema:duration(),
           #{ desc =>
 "Time interval to clear completed but stale transactions.
-Ensure that the number of completed transactions is less than the max_history."
+Ensure that the number of completed transactions is less than the <code>max_history</code>."
            , default => "5m"
            })}
     ];
diff --git a/scripts/spellcheck b/scripts/spellcheck
index 05dcef804..869e6637b 100755
--- a/scripts/spellcheck
+++ b/scripts/spellcheck
@@ -7,7 +7,7 @@ else
     SCHEMA="$1"
 fi
 
-docker run -d --name langtool "ghcr.io/iequ1/emqx-schema-validate:0.2.0"
+docker run -d --name langtool "ghcr.io/iequ1/emqx-schema-validate:0.2.1"
 
 docker exec -i langtool ./emqx_schema_validate - < "${SCHEMA}"
 success="$?"