From 0fcb3a1e930bec3d58cc34d5706f4162ce93e2d2 Mon Sep 17 00:00:00 2001
From: Zaiming Shi <zmstone@gmail.com>
Date: Tue, 19 Oct 2021 17:22:41 +0200
Subject: [PATCH] docs: add more schema docs for authz

---
 apps/emqx/src/emqx_schema.erl                 |  7 +++++++
 apps/emqx_machine/src/emqx_machine_schema.erl | 14 +++++++++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl
index 3bdc0e28c..f9b429e16 100644
--- a/apps/emqx/src/emqx_schema.erl
+++ b/apps/emqx/src/emqx_schema.erl
@@ -165,6 +165,13 @@ fields("authorization") ->
     [ {"no_match",
        sc(hoconsc:enum([allow, deny]),
           #{ default => allow
+             %% TODO: make sources a reference link
+           , desc => """
+Default access control action if the user or client matches no ACL rules,
+or if no such user or client is found by the configurable authorization
+sources such as built-in-database, an HTTP API, or a query against PostgreSQL.
+Find more details in 'authorization.sources' config.
+"""
            })}
     , {"deny_action",
        sc(hoconsc:enum([ignore, disconnect]),
diff --git a/apps/emqx_machine/src/emqx_machine_schema.erl b/apps/emqx_machine/src/emqx_machine_schema.erl
index a124166e5..08bbeb449 100644
--- a/apps/emqx_machine/src/emqx_machine_schema.erl
+++ b/apps/emqx_machine/src/emqx_machine_schema.erl
@@ -88,9 +88,17 @@ roots() ->
            })}
     , {"authorization",
        sc(hoconsc:ref("authorization"),
-          #{ desc => "In EMQ X, MQTT client access control can be just a few "
-                     "lines of text based rules, or delegated to an external "
-                     "HTTP API, or base externa database query results."
+          #{ desc => """
+Authorization a.k.a ACL.<br>
+In EMQ X, MQTT client access control is extremly flexible.<br>
+A an out of the box set of authorization data sources are supported.
+For example,<br>
+'file' source is to support concise and yet generic ACL rules in a file;<br>
+'built-in-database' source can be used to store per-client customisable rule sets,
+natively in the EMQ X node;<br>
+'http' source to make EMQ X call an external HTTP API to make the decision;<br>
+'postgresql' etc. to look up clients or rules from external databases;<br>
+"""
            })}
     ] ++
     emqx_schema:roots(medium) ++