Improve documentation around banning (#9088)

* Fix ban chatcommand description
* Correct ban API documentation

diff --git a/builtin/game/chat.lua b/builtin/game/chat.lua
index 424cbfe3f8dc3382844aba95a418e6862a52c339..37d12c458e9dbcbd5b4749535e39eaeb52b49993 100644 (file)
--- a/builtin/game/chat.lua
+++ b/builtin/game/chat.lua
@@ -909,8 +909,8 @@ core.register_chatcommand("shutdown", {
 })
 
 core.register_chatcommand("ban", {
-       params = "[<name> | <IP_address>]",
-       description = "Ban player or show ban list",
+       params = "[<name>]",
+       description = "Ban the IP of a player or show the ban list",
        privs = {ban=true},
        func = function(name, param)
                if param == "" then
@@ -922,7 +922,7 @@ core.register_chatcommand("ban", {
                        end
                end
                if not core.get_player_by_name(param) then
-                       return false, "No such player."
+                       return false, "Player is not online."
                end
                if not core.ban_player(param) then
                        return false, "Failed to ban player."
@@ -935,7 +935,7 @@ core.register_chatcommand("ban", {
 
 core.register_chatcommand("unban", {
        params = "<name> | <IP_address>",
-       description = "Remove player ban",
+       description = "Remove IP ban belonging to a player/IP",
        privs = {ban=true},
        func = function(name, param)
                if not core.unban_player_or_ip(param) then

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 1905eff4455551120fc31ed5ce4477bdd78f90fa..c0501f6bf512c3b756499a91a022909760d2f57c 100644 (file)
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -4896,13 +4896,16 @@ Server
 Bans
 ----
 
-* `minetest.get_ban_list()`: returns the ban list
-  (same as `minetest.get_ban_description("")`).
-* `minetest.get_ban_description(ip_or_name)`: returns ban description (string)
-* `minetest.ban_player(name)`: ban a player
-* `minetest.unban_player_or_ip(name)`: unban player or IP address
-* `minetest.kick_player(name, [reason])`: disconnect a player with a optional
+* `minetest.get_ban_list()`: returns a list of all bans formatted as string
+* `minetest.get_ban_description(ip_or_name)`: returns list of bans matching
+  IP address or name formatted as string
+* `minetest.ban_player(name)`: ban the IP of a currently connected player
+    * Returns boolean indicating success
+* `minetest.unban_player_or_ip(ip_or_name)`: remove ban record matching
+  IP address or name
+* `minetest.kick_player(name, [reason])`: disconnect a player with an optional
   reason.
+    * Returns boolean indicating success (false if player nonexistant)
 
 Particles
 ---------