Improve the documentation for chat command definition in lua_api.txt (#13168)

1 files changed, 30 insertions, 7 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 61743e5f4..80d7580d8 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -9299,20 +9299,31 @@ Chat command definition
 
 Used by `minetest.register_chatcommand`.
 
+Specifies the function to be called and the privileges required when a player
+issues the command.  A help message that is the concatenation of the params and
+description fields is shown when the "/help" chatcommand is issued.
+
     {
-        params = "<name> <privilege>",  -- Short parameter description
+        params = "",
+        -- Short parameter description.  See the below note.
 
-        description = "Remove privilege from player",  -- Full description
+        description = "",
+        -- General description of the command's purpose.
 
-        privs = {privs=true},  -- Require the "privs" privilege to run
+        privs = {},
+        -- Required privileges to run. See `minetest.check_player_privs()` for
+        -- the format and see [Privileges] for an overview of privileges.
 
         func = function(name, param),
-        -- Called when command is run. Returns boolean success and text output.
-        -- Special case: The help message is shown to the player if `func`
-        -- returns false without a text output.
+        -- Called when command is run.  
+        -- * `name` is the name of the player who issued the command.
+        -- * `param` is a string with the full arguments to the command.
+        -- Returns a boolean for success and a string value.  
+        -- The string is shown to the issuing player upon exit of `func` or,
+        -- if `func` returns `false` and no string, the help message is shown.
     }
 
-Note that in params, use of symbols is as follows:
+Note that in params, the conventional use of symbols is as follows:
 
 * `<>` signifies a placeholder to be replaced when the command is used. For
   example, when a player name is needed: `<name>`
@@ -9324,6 +9335,18 @@ Note that in params, use of symbols is as follows:
 * `()` signifies grouping. For example, when param1 and param2 are both
   required, or only param3 is required: `(<param1> <param2>) | <param3>`
 
+Example:
+
+    {
+        params = "<name> <privilege>",
+
+        description = "Remove privilege from player",
+
+        privs = {privs=true},  -- Require the "privs" privilege to run
+
+        func = function(name, param),
+    }
+
 Privilege definition
 --------------------