Merge pull request #10936 from zmstone/0603-imporove-desc

docs: refine some desc

apps/emqx_dashboard/src/emqx_dashboard_error_code_api.erl

@@ -63,7 +63,7 @@ schema("/error_codes/:code") ->
         'operationId' => error_code,
         get => #{
             security => [],
-            description => ?DESC(error_codes_u),
+            description => ?DESC(error_codes),
             tags => [<<"Error Codes">>],
             parameters => [
                 {code,

apps/emqx_dashboard/src/emqx_dashboard_monitor_api.erl

@@ -65,7 +65,7 @@ schema("/monitor_current") ->
         'operationId' => monitor_current,
         get => #{
             tags => [<<"Metrics">>],
-            description => ?DESC(current_status),
+            description => ?DESC(current_stats),
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(sampler_current), #{})
             }
@@ -76,7 +76,7 @@ schema("/monitor_current/nodes/:node") ->
         'operationId' => monitor_current,
         get => #{
             tags => [<<"Metrics">>],
-            description => ?DESC(current_status_node),
+            description => ?DESC(current_stats_node),
             parameters => [parameter_node()],
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(sampler_current), #{}),

apps/emqx_ft/src/emqx_ft_schema.erl

@@ -72,6 +72,7 @@ fields(file_transfer) ->
                 #{
                     desc => ?DESC("init_timeout"),
                     required => false,
+                    importance => ?IMPORTANCE_LOW,
                     default => "10s"
                 }
             )},
@@ -81,6 +82,7 @@ fields(file_transfer) ->
                 #{
                     desc => ?DESC("store_segment_timeout"),
                     required => false,
+                    importance => ?IMPORTANCE_LOW,
                     default => "5m"
                 }
             )},
@@ -90,6 +92,7 @@ fields(file_transfer) ->
                 #{
                     desc => ?DESC("assemble_timeout"),
                     required => false,
+                    importance => ?IMPORTANCE_LOW,
                     default => "5m"
                 }
             )},

apps/emqx_management/src/emqx_mgmt_api_trace.erl

@@ -206,7 +206,7 @@ fields(log_file_detail) ->
     fields(node) ++
         [
             {size, hoconsc:mk(integer(), #{description => ?DESC(file_size)})},
-            {mtime, hoconsc:mk(integer(), #{description => ?DESC(modification_date)})}
+            {mtime, hoconsc:mk(integer(), #{description => ?DESC(file_mtime)})}
         ];
 fields(trace) ->
     [
@@ -214,7 +214,7 @@ fields(trace) ->
             hoconsc:mk(
                 binary(),
                 #{
-                    description => ?DESC(format),
+                    description => ?DESC(trace_name),
                     validator => fun ?MODULE:validate_name/1,
                     required => true,
                     example => <<"EMQX-TRACE-1">>

rel/i18n/emqx_bridge_iotdb.hocon

@@ -42,7 +42,9 @@ config_is_aligned.label:
 """Align Timeseries"""
 
 config_device_id.desc:
-"""A fixed device name this data should be inserted for. If empty it must either be set in the rule action, the message itself, or it will be extracted from the topic."""
+"""The IoTDB device ID this data should be inserted for.
+If left empty, the MQTT message payload must contain a `device_id` field,
+or EMQX's rule-engine SQL must produce a `device_id` field."""
 config_device_id.label:
 """Device ID"""
 

rel/i18n/emqx_dashboard_error_code_api.hocon

@@ -5,9 +5,4 @@ error_codes.desc:
 error_codes.label:
 """API Error Codes"""
 
-error_codes_u.desc:
-"""API Error Codes"""
-error_codes_u.label:
-"""API Error Codes"""
-
 }

rel/i18n/emqx_dashboard_monitor_api.hocon

@@ -1,23 +1,23 @@
 emqx_dashboard_monitor_api {
 
 list_monitor.desc:
-"""List monitor data."""
+"""List monitor (statistics) data for the whole cluster."""
 list_monitor.label:
-"""List monitor data."""
+"""List cluster stats data"""
 
 list_monitor_node.desc:
-"""List the monitor data on the node."""
+"""List the monitor (statistics) data on the specified node."""
 list_monitor_node.label:
-"""List the monitor data on the node."""
+"""List node's stats data"""
 
-current_status.desc:
-"""Current status. Gauge and rate."""
-current_status.label:
-"""Current status. Gauge and rate."""
+current_stats.desc:
+"""Current monitor (statistics) data, e.g. number of connections and connection rate in the whole cluster."""
+current_stats.label:
+"""Cluster runtime stats"""
 
-current_status_node.desc:
-"""Node current status. Gauge and rate."""
-current_status_node.label:
-"""Node current status. Gauge and rate."""
+current_stats_node.desc:
+"""Node monitor (statistics) data, e.g. number of connections and connection rate on the specified node."""
+current_stats_node.label:
+"""Node runtime stats"""
 
 }

rel/i18n/emqx_ft_schema.hocon

@@ -7,16 +7,16 @@ This toggle also affects the availability of the File Transfer REST API and
 storage-dependent background activities (e.g. garbage collection)."""
 
 init_timeout.desc:
-"""Timeout for initializing the file transfer.<br/>
-After reaching the timeout, `init` message will be acked with an error"""
+"""Timeout for EMQX to initialize the file transfer.<br/>
+After reaching the timeout (e.g. due to system is overloaded), the PUBACK message for `init` will contain error code (0x80)."""
 
 assemble_timeout.desc:
 """Timeout for assembling and exporting file segments into a final file.<br/>
-After reaching the timeout, `fin` message will be acked with an error"""
+After reaching the timeout (e.g. due to system is overloaded), the PUBACK message for `fin` will contain error code (0x80)"""
 
 store_segment_timeout.desc:
 """Timeout for storing a file segment.<br/>
-After reaching the timeout, message with the segment will be acked with an error"""
+After reaching the timeout (e.g. due to system overloaded), the PUBACK message will contain error code (0x80)."""
 
 storage_backend.desc:
 """Storage settings for file transfer."""

rel/i18n/emqx_mgmt_api_configs.hocon

@@ -6,9 +6,9 @@ get_conf_node.label:
 """Get all the configurations for node."""
 
 node_name.desc:
-"""Node's name: If you do not fill in the fields, this node will be used by default."""
+"""Node's name. If not specified, the configs on the node which receives the HTTP request will be returned."""
 node_name.label:
-"""Node's name."""
+"""Node's name"""
 
 rest_conf_query.desc:
 """Reset the config entry specified by the query string parameter `conf_path`.<br/>

rel/i18n/emqx_mgmt_api_listeners.hocon

@@ -3,12 +3,12 @@ emqx_mgmt_api_listeners {
 list_node_live_statuses.desc:
 """List all running node's listeners live status. group by listener type"""
 list_node_live_statuses.label:
-"""List all running node's listeners live status. group by listener type"""
+"""List listeners live status"""
 
 list_listeners.desc:
 """List all running node's listeners for the specified type."""
 list_listeners.label:
-"""List all running node's listeners for the specified type."""
+"""List listeners per type"""
 
 listener_type.desc:
 """Listener type"""
@@ -18,42 +18,37 @@ listener_type.label:
 create_on_all_nodes.desc:
 """Create the specified listener on all nodes."""
 create_on_all_nodes.label:
-"""Create the specified listener on all nodes."""
+"""Create listener"""
 
 list_by_id.desc:
 """List all running node's listeners for the specified id."""
 list_by_id.label:
-"""List all running node's listeners for the specified id."""
+"""List listeners per ID"""
 
 update_lisener.desc:
 """Update the specified listener on all nodes."""
 update_lisener.label:
-"""Update the specified listener on all nodes."""
-
-create_on_all_nodes_2.desc:
-"""Create the specified listener on all nodes."""
-create_on_all_nodes_2.label:
-"""Create the specified listener on all nodes."""
+"""Update listener"""
 
 delete_on_all_nodes.desc:
 """Delete the specified listener on all nodes."""
 delete_on_all_nodes.label:
-"""Delete the specified listener on all nodes."""
+"""Delete listener"""
 
 start_on_all_nodes.desc:
 """Start the listener on all nodes."""
 start_on_all_nodes.label:
-"""Start the listener on all nodes."""
+"""Start listener"""
 
 stop_on_all_nodes.desc:
 """Stop the listener on all nodes."""
 stop_on_all_nodes.label:
-"""Stop the listener on all nodes."""
+"""Stop listener"""
 
 restart_on_all_nodes.desc:
 """Restart listeners on all nodes."""
 restart_on_all_nodes.label:
-"""Restart listeners on all nodes."""
+"""Restart listener"""
 
 
 }

rel/i18n/emqx_mgmt_api_nodes.hocon

@@ -11,12 +11,12 @@ get_node_info.label:
 """Get node info"""
 
 get_node_metrics.desc:
-"""Get node metrics"""
+"""Get node run-time counter metrics. Such as received or sent bytes or messages, the number of succeeded or failed authentications or authorizations, etc."""
 get_node_metrics.label:
 """Get node metrics"""
 
 get_node_stats.desc:
-"""Get node stats"""
+"""Get node run-time stats. Such as the number of topics, connections, etc."""
 get_node_stats.label:
 """Get node stats"""
 

rel/i18n/emqx_mgmt_api_trace.hocon

@@ -50,15 +50,15 @@ file_size.desc:
 file_size.label:
 """file size"""
 
-modification_date.desc:
-"""the modification and last access times of a file"""
-modification_date.label:
-"""last access time"""
+file_mtime.desc:
+"""The last time this file is modified."""
+file_mtime.label:
+"""file mtime"""
 
-format.desc:
-"""Unique and format by [a-zA-Z0-9-_]"""
-format.label:
-"""Unique and format by [a-zA-Z0-9-_]"""
+trace_name.desc:
+"""Unique name of the trace. Only ascii letters in a-z, A-Z, 0-9 and underscore '_' are allowed."""
+trace_name.label:
+"""Unique name of the trace"""
 
 filter_type.desc:
 """Filter type"""
@@ -66,19 +66,19 @@ filter_type.label:
 """Filter type"""
 
 support_wildcard.desc:
-"""support mqtt wildcard topic."""
+"""Specify the topic or topic filter if the trace 'type' is 'topic'."""
 support_wildcard.label:
-"""support mqtt wildcard topic"""
+"""MQTT Topic"""
 
 mqtt_clientid.desc:
-"""mqtt clientid."""
+"""Specify the MQTT clientid if the trace 'type' is 'clientid'."""
 mqtt_clientid.label:
-"""mqtt clientid"""
+"""MQTT clientid"""
 
 client_ip_addess.desc:
-"""client ip address"""
+"""Specify the client's IP address if the trace type is 'ip_address'."""
 client_ip_addess.label:
-"""client ip address"""
+"""Client IP Address"""
 
 trace_status.desc:
 """trace status"""
@@ -90,11 +90,6 @@ time_format.desc:
 time_format.label:
 """rfc3339 timestamp or epoch second"""
 
-time_format_g.desc:
-"""rfc3339 timestamp or epoch second"""
-time_format_g.label:
-"""rfc3339 timestamp or epoch second"""
-
 trace_log_size.desc:
 """trace log size"""
 trace_log_size.label:

scripts/spellcheck/dicts/emqx.txt

@@ -52,7 +52,9 @@ PINGREQ
 PSK
 PSK
 PSKs
+PUBACK
 PUBREL
+PUBLISH
 QoS
 RESTful
 ROADMAP