yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Fix typos

This commit is contained in:
k32 2022-02-17 19:48:46 +01:00
parent 2a6d11c7f1
commit 5638bcb92b
17 changed files with 79 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
apps/emqx/src/emqx_limiter/src/emqx_limiter_schema.erl
View File

@ -72,7 +72,7 @@ fields(limiter_opts) ->
[ {global, sc(ref(rate_burst), #{})}
, {zone, sc(map("zone name", ref(rate_burst)), #{})}
, {bucket, sc(map("bucket_id", ref(bucket)),
#{desc => "token bucket"})}
#{desc => "Token bucket"})}
];
fields(rate_burst) ->
@ -81,7 +81,7 @@ fields(rate_burst) ->
];
fields(bucket) ->
[ {zone, sc(atom(), #{desc => "the zone which the bucket in"})}
[ {zone, sc(atom(), #{desc => "The bucket's zone"})}
, {aggregated, sc(ref(bucket_aggregated), #{})}
, {per_client, sc(ref(client_bucket), #{})}
];
@ -100,18 +100,18 @@ fields(client_bucket) ->
%% so we need to use this value to prevent excessive consumption
%% (e.g, consumption from an empty bucket)
, {low_water_mark, sc(initial(),
#{desc => "if the remaining tokens are lower than this value,
the check/consume will succeed, but it will be forced to hang for a short period of time",
#{desc => "If the remaining tokens are lower than this value,
the check/consume will succeed, but it will be forced to wait for a short period of time.",
default => "0"})}
, {capacity, sc(capacity(), #{desc => "the capacity of the token bucket"})}
, {capacity, sc(capacity(), #{desc => "The capacity of the token bucket."})}
, {divisible, sc(boolean(),
#{desc => "is it possible to split the number of tokens requested",
#{desc => "Is it possible to split the number of requested tokens?",
default => false})}
, {max_retry_time, sc(emqx_schema:duration(),
#{ desc => "the maximum retry time when acquire failed"
#{ desc => "The maximum retry time when acquire failed."
, default => "5s"})}
, {failure_strategy, sc(failure_strategy(),
#{ desc => "the strategy when all retry failed"
#{ desc => "The strategy when all the retries failed."
, default => force})}
].

39
apps/emqx/src/emqx_schema.erl
View File

@ -101,7 +101,7 @@ roots(high) ->
"""A zone is a set of configs grouped by the zone <code>name</code>.<br>
For flexible configuration mapping, the <code>name</code>
can be set to a listener's <code>zone</code> config.<br>
NOTE: A builtin zone named <code>default</code> is auto created
NOTE: A built-in zone named <code>default</code> is auto created
and can not be deleted."""
})}
, {"mqtt",
@ -337,7 +337,7 @@ message within this interval."""
, {"ignore_loop_deliver",
sc(boolean(),
#{ default => false,
desc => "Ignore loop delivery of messages for mqtt v3.1.1."
desc => "Ignore loop delivery of messages for MQTT v3.1.1."
})}
, {"strict_mode",
sc(boolean(),
@ -357,9 +357,9 @@ This feature is disabled if is set to \"\"."""
sc(hoconsc:union([integer(), disabled]),
#{ default => disabled,
desc =>
"""Server Keep Alive of MQTT 5.0.
If the Server returns a Server Keep Alive on the CONNACK packet,
the Client MUST use that value instead of the value it sent as the Keep Alive."""
"""'Server Keep Alive' of MQTT 5.0.
If the server returns a 'Server Keep Alive' in the CONNACK packet,
the client MUST use that value instead of the value it sent as the 'Keep Alive'."""
})
}
, {"keepalive_backoff",
@ -430,17 +430,18 @@ Priority number [1-255]<br>
**NOTE**: Comma and equal signs are not allowed for priority topic names.<br>
**NOTE**: Messages for topics not in the priority table are treated as
either highest or lowest priority depending on the configured value for mqtt.mqueue_default_priority.
either highest or lowest priority depending on the configured value for
<code>mqtt.mqueue_default_priority</code>.
<br><br>
**Examples**:
To configure \"topic/1\" > \"topic/2\":
mqueue_priorities: {\"topic/1\": 10, \"topic/2\": 8}"""
To configure <code>\"topic/1\" > \"topic/2\"</code>:<br/>
<code>mqueue_priorities: {\"topic/1\": 10, \"topic/2\": 8}</code>"""
})
}
, {"mqueue_default_priority",
sc(hoconsc:enum([highest, lowest]),
#{ default => lowest,
desc => "Default to highest priority for topics not matching priority table."
desc => "Default to the highest priority for topics not matching priority table."
})
}
, {"mqueue_store_qos0",
@ -452,7 +453,7 @@ mqueue_priorities: {\"topic/1\": 10, \"topic/2\": 8}"""
, {"use_username_as_clientid",
sc(boolean(),
#{ default => false,
desc => "Replace client id with the username."
desc => "Replace client ID with the username."
})
}
, {"peer_cert_as_username",
@ -1045,7 +1046,7 @@ in the VM exceeds this value"
sc(string(),
#{ mapping => "system_monitor.db_username"
, default => "system_monitor"
, desc => "EMQX user name in the PostgreSQL database"
, desc => "EMQX username in the PostgreSQL database"
})
}
, {"db_password",
@ -1071,10 +1072,10 @@ fields("alarm") ->
validator => fun ?MODULE:validate_alarm_actions/1,
example => [log, publish],
desc =>
"""The actions triggered when the alarm is activated.<\br>
Currently support two actions, 'log' and 'publish'.
'log' is to write the alarm to log (console or file).
'publish' is to publish the alarm as an MQTT message to the system topics:
"""The actions triggered when the alarm is activated.<br/>
Currently, the following actions are supported: <code>log</code> and <code>publish</code>.
<code>log</code> is to write the alarm to log (console or file).
<code>publish</code> is to publish the alarm as an MQTT message to the system topics:
<code>$SYS/brokers/emqx@xx.xx.xx.x/alarms/activate</code> and
<code>$SYS/brokers/emqx@xx.xx.xx.x/alarms/deactivate</code>"""
})
@ -1216,7 +1217,7 @@ already established connections.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should placed at the end of
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
"""
})
@ -1251,7 +1252,7 @@ the file if it is to be added.
, nullable => true
, desc =>
"""String containing the user's password. Only used if the private
keyfile is password-protected."""
key file is password-protected."""
})
}
, {"versions",
@ -1302,7 +1303,7 @@ server_ssl_opts_schema(Defaults, IsRanchListener) ->
to be used by the server if a cipher suite using Diffie Hellman
key exchange is negotiated. If not specified, default parameters
are used.<br>
NOTE: The dhfile option is not supported by TLS 1.3."""
NOTE: The <code>dhfile</code> option is not supported by TLS 1.3."""
})
}
, {"fail_if_no_peer_cert",
@ -1463,7 +1464,7 @@ ref(Field) -> hoconsc:ref(?MODULE, Field).
ref(Module, Field) -> hoconsc:ref(Module, Field).
mk_duration(Desc, OverrideMeta) ->
DefaultMeta = #{desc => Desc ++ " Time span. A text string with number followed by time units:
DefaultMeta = #{desc => Desc ++ " time span. A text string with number followed by time units:
`ms` for milliseconds,
`s` for seconds,
`m` for minutes,

9
apps/emqx_authz/src/emqx_authz_schema.erl
View File

@ -69,11 +69,10 @@ fields("authorization") ->
"""
Authorization data sources.<br>
An array of authorization (ACL) data providers.
It is designed as an array but not a hash-map so the sources can be
It is designed as an array, not a hash-map, so the sources can be
ordered to form a chain of access controls.<br>
When authorizing a publish or subscribe action, the configured
When authorizing a 'publish' or 'subscribe' action, the configured
sources are checked in order. When checking an ACL source,
in case the client (identified by username or client ID) is not found,
it moves on to the next source. And it stops immediately
@ -100,7 +99,7 @@ If the file provisioned before starting EMQX node,
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` sub directory inside EMQX's `data_dir`,
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.
"""
}}
@ -145,7 +144,7 @@ fields(redis_cluster) ->
http_common_fields() ->
[ {url, fun url/1}
, {request_timeout, mk_duration("request timeout", #{default => "30s"})}
, {request_timeout, mk_duration("Request timeout", #{default => "30s"})}
, {body, #{type => map(), nullable => true}}
] ++ proplists:delete(base_url, connector_fields(http)).

10
apps/emqx_bridge/src/emqx_bridge_http_schema.erl
View File

@ -25,9 +25,9 @@ is not allowed.
})}
, {local_topic, mk(binary(),
#{ desc =>"""
The MQTT topic filter to be forwarded to the HTTP server. All MQTT PUBLISH messages which topic
match the local_topic will be forwarded.<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
The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.<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 match
local_topic will be forwarded.
"""
})}
@ -89,7 +89,7 @@ basic_config() ->
})}
, {direction,
mk(egress,
#{ desc => "The direction of this bridge, MUST be egress"
#{ desc => "The direction of this bridge, MUST be 'egress'"
, default => egress
})}
]
@ -97,7 +97,7 @@ basic_config() ->
%%======================================================================================
id_field() ->
{id, mk(binary(), #{desc => "The Bridge Id", example => "http:my_http_bridge"})}.
{id, mk(binary(), #{desc => "The Bridge ID", example => "http:my_http_bridge"})}.
type_field() ->
{type, mk(http, #{desc => "The Bridge Type"})}.

4
apps/emqx_bridge/src/emqx_bridge_mqtt_schema.erl
View File

@ -43,7 +43,7 @@ fields("get_egress") ->
%%======================================================================================
id_field() ->
{id, mk(binary(), #{desc => "The Bridge Id", example => "mqtt:my_mqtt_bridge"})}.
{id, mk(binary(), #{desc => "The bridge ID", example => "mqtt:my_mqtt_bridge"})}.
type_field() ->
{type, mk(mqtt, #{desc => "The Bridge Type"})}.
{type, mk(mqtt, #{desc => "The bridge type"})}.

3
apps/emqx_bridge/src/emqx_bridge_schema.erl
View File

@ -55,7 +55,8 @@ common_bridge_fields() ->
#{ nullable => false
, example => <<"mqtt:my_mqtt_connector">>
, desc =>"""
The connector Id to be used for this bridge. Connector Ids must be of format: '{type}:{name}'.<br>
The connector ID to be used for this bridge. Connector IDs must be of format:
<code>{type}:{name}</code>.<br>
In config files, you can find the corresponding config entry for a connector by such path: 'connectors.{type}.{name}'.<br>
"""
})}

2
apps/emqx_conf/etc/emqx_conf.md
View File

@ -111,7 +111,7 @@ Environment variables can be used to define or override config values.
Due to the fact that dots (`.`) are not allowed in environment variables, dots are
replaced with double-underscores (`__`).
And a the `EMQX_` prefix is used as the namespace.
And the `EMQX_` prefix is used as the namespace.
For example `node.name` can be represented as `EMQX_NODE__NAME`

6
apps/emqx_conf/src/emqx_conf_schema.erl
View File

@ -317,7 +317,7 @@ a crash dump
})}
, {"etc_dir",
sc(string(),
#{ desc => "`etc` dir for the node"
#{ desc => "<code>etc</code> dir for the node"
}
)}
, {"cluster_call",
@ -915,9 +915,9 @@ emqx_schema_high_prio_roots() ->
Authz = {"authorization",
sc(hoconsc:ref("authorization"),
#{ desc => """
Authorization a.k.a ACL.<br>
Authorization a.k.a. ACL.<br>
In EMQX, MQTT client access control is extremely flexible.<br>
An out of the box set of authorization data sources are supported.
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 customizable rule sets,

2
apps/emqx_connector/include/emqx_connector.hrl
View File

@ -24,7 +24,7 @@
-define(REDIS_DEFAULT_PORT, 6379).
-define(PGSQL_DEFAULT_PORT, 5432).
-define(SERVERS_DESC, "A Node list for Cluster to connect to. The nodes should be splited with ',', such as: 'Node[,Node]'<br>\nFor each Node should be:<br>").
-define(SERVERS_DESC, "A Node list for Cluster to connect to. The nodes should be split with ',', such as: 'Node[,Node]'<br>\nFor each Node should be:<br>").
-define(SERVER_DESC(TYPE, DEFAULT_PORT), """
The IPv4 or IPv6 address or host name to connect to.<br>

14
apps/emqx_connector/src/mqtt/emqx_connector_mqtt_schema.erl
View File

@ -44,7 +44,7 @@ fields("connector") ->
, desc => """
The mode of the MQTT Bridge. Can be one of 'cluster_singleton' or 'cluster_shareload'<br>
- cluster_singleton: create an 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>
- cluster_shareload: create an MQTT connection on each node in the emqx cluster.<br>
@ -65,7 +65,7 @@ topic filters for 'remote_topic' of ingress connections.
#{ default => "127.0.0.1:1883"
, desc => "The host and port of the remote MQTT broker"
})}
, {reconnect_interval, mk_duration("reconnect interval", #{default => "15s"})}
, {reconnect_interval, mk_duration("Reconnect interval", #{default => "15s"})}
, {proto_ver,
sc(hoconsc:enum([v3, v4, v5]),
#{ default => v4
@ -86,12 +86,12 @@ topic filters for 'remote_topic' of ingress connections.
#{ default => true
, desc => "The clean-start or the clean-session of the MQTT protocol"
})}
, {keepalive, mk_duration("keepalive", #{default => "300s"})}
, {retry_interval, mk_duration("retry interval", #{default => "15s"})}
, {keepalive, mk_duration("Keepalive", #{default => "300s"})}
, {retry_interval, mk_duration("Retry interval", #{default => "15s"})}
, {max_inflight,
sc(integer(),
#{ default => 32
, desc => "Max inflight messages (sent but ACK has not received) of the MQTT protocol"
, desc => "Max inflight (sent, but un-acked) messages of the MQTT protocol"
})}
, {replayq,
sc(ref("replayq"),
@ -180,7 +180,7 @@ A segment is mapping to a file in the replayq dir. If the current segment is ful
#{ default => false
, desc => """
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 write to the replayq files after the size of
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'.
"""
})}
@ -223,7 +223,7 @@ common_inout_confs() ->
sc(hoconsc:union([boolean(), binary()]),
#{ default => <<"${retain}">>
, 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."""
})}
, {payload,

2
apps/emqx_gateway/src/emqx_gateway_api_clients.erl
View File

@ -643,7 +643,7 @@ fields(subscription) ->
fields(extra_sub_props) ->
[ {subid,
mk(binary(),
#{ desc => <<"Only stomp protocol, an uniquely identity for "
#{ desc => <<"Only stomp protocol, a unique identity for "
"the subscription. range: 1-65535.">>})}
].

22
apps/emqx_gateway/src/emqx_gateway_schema.erl
View File

@ -122,7 +122,7 @@ fields(mqttsn) ->
#{ default => 1
, nullable => false
, desc =>
"MQTT-SN Gateway Id.<br>
"MQTT-SN Gateway ID.<br>
When the <code>broadcast</code> option is enabled,
the gateway will broadcast ADVERTISE message with this value"
})}
@ -140,22 +140,22 @@ the gateway will broadcast ADVERTISE message with this value"
This feature is defined for very simple client implementations
which do not support any other features except this one.<br>
There is no connection setup nor tear down, no registration nor subscription.<br>
The client just sends its PUBLISH messages to a GW"
The client just sends its 'PUBLISH' messages to a GW"
})}
, {predefined,
sc(hoconsc:array(ref(mqttsn_predefined)),
#{ default => []
, nullable => {true, recursively}
, desc =>
<<"The Pre-defined topic ids and topic names.<br>
A 'pre-defined' topic id is a topic id whose mapping to a topic name
is known in advance by both the client’s application and the gateway">>
<<"The pre-defined topic IDs and topic names.<br>
A 'pre-defined' topic ID is a topic ID whose mapping to a topic name
is known in advance by both the client's application and the gateway">>
})}
, {listeners, sc(ref(udp_listeners))}
] ++ gateway_common_options();
fields(mqttsn_predefined) ->
[ {id, sc(integer(), #{desc => "Topic Id.<br>Range: 1-65535"})}
[ {id, sc(integer(), #{desc => "Topic ID.<br>Range: 1-65535"})}
, {topic, sc(binary(), #{desc => "Topic Name"})}
];
@ -322,7 +322,7 @@ fields(lwm2m_translators) ->
#{ desc =>
"The topic for receiving downstream commands.<br>
For each new LwM2M client that succeeds in going online, the gateway creates
a the subscription relationship to receive downstream commands and send it to
a subscription relationship to receive downstream commands and send it to
the LwM2M client"
, nullable => false
})}
@ -336,8 +336,8 @@ the LwM2M client"
sc(ref(translator),
#{ desc =>
"The topic for gateway to publish the notify events from LwM2M client.<br>
After succeed observe a resource of LwM2M client, Gateway will send the
notifyevents via this topic, if the client reports any resource changes"
After succeed observe a resource of LwM2M client, Gateway will send the
notify events via this topic, if the client reports any resource changes"
, nullable => false
})}
, {register,
@ -425,7 +425,7 @@ authentication_schema() ->
sc(emqx_authn_schema:authenticator_type(),
#{ nullable => {true, recursively}
, desc =>
"""Default authentication configs for all of the gateway listeners.<br>
"""Default authentication configs for all the gateway listeners.<br>
For per-listener overrides see <code>authentication</code>
in listener configs"""
}).
@ -446,7 +446,7 @@ gateway_common_options() ->
#{ default => <<"30s">>
, desc =>
"The idle time of the client connection process.<br>
it has two purposes:
It has two purposes:
1. A newly created client process that does not receive any client requests
after that time will be closed directly.
2. A running client process that does not receive any client requests after

6
apps/emqx_plugins/src/emqx_plugins_schema.erl
View File

@ -80,10 +80,10 @@ install_dir(nullable) -> true;
install_dir(default) -> "plugins"; %% runner's root dir
install_dir(T) when T =/= desc -> undefined;
install_dir(desc) -> """
In which directory are the external plugins installed.
The installation directory for the external plugins.
The plugin beam files and configuration files should reside in
the sub-directory named as <code>emqx_foo_bar-0.1.0</code>.
the subdirectory named as <code>emqx_foo_bar-0.1.0</code>.
<br>
NOTE: For security reasons, this directory should **NOT** be writable
by anyone expect for <code>emqx</code> (or any user which runs EMQX)
by anyone except <code>emqx</code> (or any user which runs EMQX).
""".

4
apps/emqx_psk/src/emqx_psk_schema.erl
View File

@ -58,14 +58,14 @@ init_file(desc) ->
<<"If init_file is specified, emqx will import PSKs from the file ",
"into the built-in database at startup for use by the runtime. ",
"The file has to be structured line-by-line, each line must be in ",
"the format of 'PSKIdentity:SharedSecret' for example: ",
"the format of <code>PSKIdentity:SharedSecret</code>. For example: ",
"<code>mydevice1:c2VjcmV0</code>">>;
init_file(nullable) -> true;
init_file(_) -> undefined.
separator(type) -> binary();
separator(desc) ->
<<"The separator between PSKIdentity and SharedSecret in the psk file">>;
<<"The separator between <code>PSKIdentity</code> and <code>SharedSecret</code> in the psk file">>;
separator(default) -> <<":">>;
separator(_) -> undefined.

2
apps/emqx_rule_engine/src/emqx_rule_api_schema.erl
View File

@ -211,7 +211,7 @@ qos() ->
rule_id() ->
{"id", sc(binary(),
#{ desc => "The Id of the rule", nullable => false
#{ desc => "The ID of the rule", nullable => false
, example => "293fb66f"
})}.

14
apps/emqx_rule_engine/src/emqx_rule_engine_schema.erl
View File

@ -52,12 +52,12 @@ Example: <code>SELECT * FROM \"test/topic\" WHERE payload.x = 1</code><br>
, {"outputs", sc(hoconsc:array(hoconsc:union(outputs())),
#{ desc => """
A list of outputs of the rule.<br>
An output can be a string that refers to the channel Id of a emqx bridge, or a object
An output can be a string that refers to the channel ID of an EMQX bridge, or an object
that refers to a function.<br>
There a some built-in functions like \"republish\" and \"console\", and we also support user
provided functions in the format: \"{module}:{function}\".<br>
The outputs in the list is executed one by one in order.
This means that if one of the output is executing slowly, all of the outputs comes after it will not
The outputs in the list are executed sequentially.
This means that if one of the output is executing slowly, all the following outputs will not
be executed until it returns.<br>
If one of the output crashed, all other outputs come after it will still be executed, in the
original order.<br>
@ -149,7 +149,7 @@ Template with variables is allowed, see description of the 'republish_args'.
, {qos, sc(qos(),
#{ desc => """
The qos of the message to be re-published.
Template with with variables is allowed, see description of the 'republish_args.<br>
Template with variables is allowed, see description of the 'republish_args'.<br>
Defaults to ${qos}. If variable ${qos} is not found from the selected result of the rule,
0 is used.
"""
@ -158,8 +158,8 @@ Defaults to ${qos}. If variable ${qos} is not found from the selected result of
})}
, {retain, sc(hoconsc:union([binary(), boolean()]),
#{ desc => """
The retain flag of the message to be re-published.
Template with with variables is allowed, see description of the 'republish_args.<br>
The 'retain' flag of the message to be re-published.
Template with variables is allowed, see description of the 'republish_args'.<br>
Defaults to ${retain}. If variable ${retain} is not found from the selected result
of the rule, false is used.
"""
@ -169,7 +169,7 @@ of the rule, false is used.
, {payload, sc(binary(),
#{ desc => """
The payload of the message to be re-published.
Template with with variables is allowed, see description of the 'republish_args.<br>.
Template with variables is allowed, see description of the 'republish_args'.<br>.
Defaults to ${payload}. If variable ${payload} is not found from the selected result
of the rule, then the string \"undefined\" is used.
"""

2
apps/emqx_slow_subs/src/emqx_slow_subs_schema.erl
View File

@ -9,7 +9,7 @@ namespace() -> "slow_subs".
roots() -> ["slow_subs"].
fields("slow_subs") ->
[ {enable, sc(boolean(), false, "switch of this function")}
[ {enable, sc(boolean(), false, "Enable this feature")}
, {threshold,
sc(emqx_schema:duration_ms(),
"500ms",