docs(schema): Add descriptions for authZ and connector

apps/emqx/src/emqx_schema.erl

@@ -339,17 +339,26 @@ fields("cache") ->
         {"enable",
             sc(
                 boolean(),
-                #{default => true}
+                #{
+                    default => true,
+                    desc => "Enable or disable the authorization cache."
+                }
             )},
         {"max_size",
             sc(
                 range(1, 1048576),
-                #{default => 32}
+                #{
+                    default => 32,
+                    desc => "Maximum number of cached items."
+                }
             )},
         {"ttl",
             sc(
                 duration(),
-                #{default => "1m"}
+                #{
+                    default => "1m",
+                    desc => "Time to live for the cached data."
+                }
             )}
     ];
 fields("mqtt") ->

apps/emqx_authn/src/emqx_authn_password_hashing.erl

@@ -73,14 +73,17 @@ fields(other_algorithms) ->
      {salt_position, fun salt_position/1}].
 
 salt_position(type) -> {enum, [prefix, suffix]};
+salt_position(desc) -> "Specifies whether the password salt is stored as a prefix or the suffix.";
 salt_position(default) -> prefix;
 salt_position(_) -> undefined.
 
 salt_rounds(type) -> integer();
+salt_rounds(desc) -> "Cost factor for the bcrypt hash.";
 salt_rounds(default) -> 10;
 salt_rounds(_) -> undefined.
 
 dk_length(type) -> integer();
+dk_length(desc) -> "Length of the derived key.";
 dk_length(required) -> false;
 dk_length(_) -> undefined.
 

apps/emqx_authn/src/emqx_authn_schema.erl

@@ -55,11 +55,15 @@ root_type() ->
 
 mechanism(Name) ->
     hoconsc:mk(hoconsc:enum([Name]),
-               #{required => true}).
+               #{ required => true
+                , desc => "Authentication mechanism."
+                }).
 
 backend(Name) ->
     hoconsc:mk(hoconsc:enum([Name]),
-               #{required => true}).
+               #{ required => true
+                , desc => "Backend type."
+                }).
 
 fields("metrics_status_fields") ->
     [ {"metrics", mk(ref(?MODULE, "metrics"), #{desc => "The metrics of the resource"})}
@@ -89,7 +93,7 @@ fields("node_metrics") ->
 
 fields("node_status") ->
     [ node_name()
-    , {"status", mk(status(), #{})}
+    , {"status", mk(status(), #{desc => "Status of the node."})}
     ].
 
 status() ->

apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl

@@ -26,6 +26,7 @@
 -export([ namespace/0
         , roots/0
         , fields/1
+        , desc/1
         ]).
 
 -export([ refs/0
@@ -55,6 +56,15 @@ fields('replica-set') ->
 fields('sharded-cluster') ->
     common_fields() ++ emqx_connector_mongo:fields(sharded).
 
+desc(standalone) ->
+    "Configuration for a standalone MongoDB instance.";
+desc('replica-set') ->
+    "Configuration for a replica set.";
+desc('sharded-cluster') ->
+    "Configuration for a sharded cluster.";
+desc(_) ->
+    undefined.
+
 common_fields() ->
     [ {mechanism, emqx_authn_schema:mechanism('password_based')}
     , {backend, emqx_authn_schema:backend(mongodb)}
@@ -67,19 +77,27 @@ common_fields() ->
     ] ++ emqx_authn_schema:common_fields().
 
 collection(type) -> binary();
+collection(desc) -> "Collection used to store authentication data.";
 collection(_) -> undefined.
 
 selector(type) -> map();
+selector(desc) -> "Statement that is executed during the authentication process. "
+                  "Commands can support following wildcards:\n"
+                  " - `${username}`: substituted with client's username\n"
+                  " - `${clientid}`: substituted with the clientid";
 selector(_) -> undefined.
 
 password_hash_field(type) -> binary();
+password_hash_field(desc) -> "Document field that contains password hash.";
 password_hash_field(_) -> undefined.
 
 salt_field(type) -> binary();
+salt_field(desc) -> "Document field that contains the password salt.";
 salt_field(required) -> false;
 salt_field(_) -> undefined.
 
 is_superuser_field(type) -> binary();
+is_superuser_field(desc) -> "Document field that defines if the user has superuser privileges.";
 is_superuser_field(required) -> false;
 is_superuser_field(_) -> undefined.
 

apps/emqx_authz/src/emqx_authz_schema.erl

@@ -66,7 +66,7 @@ fields("authorization") ->
                     ]),
                   default => [],
                   desc =>
-"""
+"
 Authorization data sources.<br>
 An array of authorization (ACL) data providers.
 It is designed as an array, not a hash-map, so the sources can be
@@ -84,7 +84,7 @@ the default action configured in 'authorization.no_match' is applied.<br>
 NOTE:
 The source elements are identified by their 'type'.
 It is NOT allowed to configure two or more sources of the same type.
-"""
+"
                  }
       }
     ];
@@ -94,7 +94,7 @@ fields(file) ->
                  default => true}}
     , {path, #{type => string(),
                required => true,
-               desc => """
+               desc => "
 Path to the file which contains the ACL rules.<br>
 If the file provisioned before starting EMQX node,
 it can be placed anywhere as long as EMQX has read access to it.
@@ -102,7 +102,7 @@ it can be placed anywhere as long as EMQX has read access to it.
 In case the rule-set is created from EMQX dashboard or management API,
 the file will be placed in `authz` subdirectory inside EMQX's `data_dir`,
 and the new rules will override all rules from the old config file.
-"""
+"
               }}
     ];
 fields(http_get) ->
@@ -152,11 +152,12 @@ http_common_fields() ->
                                    maps:from_list(connector_fields(http)))).
 
 mongo_common_fields() ->
-    [ {collection, #{type => atom()}}
-    , {selector, #{type => map()}}
-    , {type, #{type => mongodb}}
+    [ {collection, #{type => atom(), desc => "`MongoDB` collection containing the authorization data."}}
+    , {selector, #{type => map(), desc => "MQL query used to select the authorization record."}}
+    , {type, #{type => mongodb, desc => "Database backend."}}
     , {enable, #{type => boolean(),
-                 default => true}}
+                 default => true,
+                 desc => "Enable or disable the backend."}}
     ].
 
 validations() ->
@@ -244,6 +245,7 @@ union_array(Item) when is_list(Item) ->
 
 query() ->
     #{type => binary(),
+      desc => "",
       validator => fun(S) ->
                          case size(S) > 0 of
                              true -> ok;
@@ -264,9 +266,10 @@ connector_fields(DB, Fields) ->
               error:Reason ->
                   erlang:error(Reason)
           end,
-    [ {type, #{type => DB}}
+    [ {type, #{type => DB, desc => "Database backend."}}
     , {enable, #{type => boolean(),
-                 default => true}}
+                 default => true,
+                 desc => "Enable or disable the backend."}}
     ] ++ erlang:apply(Mod, fields, [Fields]).
 
 to_list(A) when is_atom(A) ->

apps/emqx_connector/src/emqx_connector_mongo.erl

@@ -54,13 +54,15 @@ roots() ->
 
 fields(single) ->
     [ {mongo_type, #{type => single,
-                     default => single}}
+                     default => single,
+                     desc => "Standalone instance."}}
     , {server, fun server/1}
     , {w_mode, fun w_mode/1}
     ] ++ mongo_fields();
 fields(rs) ->
     [ {mongo_type, #{type => rs,
-                     default => rs}}
+                     default => rs,
+                     desc => "Replica set."}}
     , {servers, fun servers/1}
     , {w_mode, fun w_mode/1}
     , {r_mode, fun r_mode/1}
@@ -68,7 +70,8 @@ fields(rs) ->
     ] ++ mongo_fields();
 fields(sharded) ->
     [ {mongo_type, #{type => sharded,
-                     default => sharded}}
+                     default => sharded,
+                     desc => "Sharded cluster."}}
     , {servers, fun servers/1}
     , {w_mode, fun w_mode/1}
     ] ++ mongo_fields();
@@ -306,22 +309,27 @@ servers(desc) -> ?SERVERS_DESC ++ server(desc);
 servers(_) -> undefined.
 
 w_mode(type) -> hoconsc:enum([unsafe, safe]);
+w_mode(desc) -> "Write mode.";
 w_mode(default) -> unsafe;
 w_mode(_) -> undefined.
 
 r_mode(type) -> hoconsc:enum([master, slave_ok]);
+r_mode(desc) -> "Read mode.";
 r_mode(default) -> master;
 r_mode(_) -> undefined.
 
 duration(type) -> emqx_schema:duration_ms();
+duration(desc) -> "Time interval, such as timeout or TTL.";
 duration(required) -> false;
 duration(_) -> undefined.
 
 replica_set_name(type) -> binary();
+replica_set_name(desc) -> "Name of the replica set.";
 replica_set_name(required) -> false;
 replica_set_name(_) -> undefined.
 
 srv_record(type) -> boolean();
+srv_record(desc) -> "Use DNS SRV record.";
 srv_record(default) -> false;
 srv_record(_) -> undefined.
 

apps/emqx_connector/src/emqx_connector_schema_lib.erl

@@ -52,7 +52,8 @@ fields(_) -> [].
 
 ssl_fields() ->
     [ {ssl, #{type => hoconsc:ref(emqx_schema, ssl_client_opts),
-              default => #{<<"enable">> => false}
+              default => #{<<"enable">> => false},
+              desc => "SSL connection settings."
              }
       }
     ].
@@ -66,24 +67,29 @@ relational_db_fields() ->
     ].
 
 database(type) -> binary();
+database(desc) -> "Database name.";
 database(required) -> true;
 database(validator) -> [?NOT_EMPTY("the value of the field 'database' cannot be empty")];
 database(_) -> undefined.
 
 pool_size(type) -> integer();
+pool_size(desc) -> "Size of the connection pool.";
 pool_size(default) -> 8;
 pool_size(validator) -> [?MIN(1)];
 pool_size(_) -> undefined.
 
 username(type) -> binary();
+username(desc) -> "EMQX's username in the external database.";
 username(required) -> false;
 username(_) -> undefined.
 
 password(type) -> binary();
+password(desc) -> "EMQX's password in the external database.";
 password(required) -> false;
 password(_) -> undefined.
 
 auto_reconnect(type) -> boolean();
+auto_reconnect(desc) -> "Enable automatic reconnect to the database.";
 auto_reconnect(default) -> true;
 auto_reconnect(_) -> undefined.