Docs: Clarify where to check for 'protection_bypass' (#8675)

diff --git a/builtin/game/item.lua b/builtin/game/item.lua
index ced28771e37b43c5d3ed137dcd4dfe0b88c7b370..7855880f895c879d8a512d9e6b9577c7daa10189 100644 (file)
--- a/builtin/game/item.lua
+++ b/builtin/game/item.lua
@@ -251,11 +251,6 @@ local function user_name(user)
        return user and user:get_player_name() or ""
 end
 
-local function is_protected(pos, name)
-       return core.is_protected(pos, name) and
-               not minetest.check_player_privs(name, "protection_bypass")
-end
-
 -- Returns a logging function. For empty names, does not log.
 local function make_log(name)
        return name ~= "" and core.log or function() end
@@ -302,7 +297,7 @@ function core.item_place_node(itemstack, placer, pointed_thing, param2,
                place_to = {x = under.x, y = under.y, z = under.z}
        end
 
-       if is_protected(place_to, playername) then
+       if core.is_protected(place_to, playername) then
                log("action", playername
                                .. " tried to place " .. def.name
                                .. " at protected position "
@@ -552,7 +547,7 @@ function core.node_dig(pos, node, digger)
                return
        end
 
-       if is_protected(pos, diggername) then
+       if core.is_protected(pos, diggername) then
                log("action", diggername
                                .. " tried to dig " .. node.name
                                .. " at protected position "

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index b25c4ec9dbf47eb1fdae4882c7aceba968a8e6d1..2650bfedf7fee614bd046f890851c9222e78b479 100644 (file)
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -4856,15 +4856,13 @@ Misc.
 * `minetest.decode_base64(string)`: returns string
     * Decodes a string encoded in base64.
 * `minetest.is_protected(pos, name)`: returns boolean
-    * Returns true, if player `name` shouldn't be able to dig at `pos` or do
-      other actions, definable by mods, due to some mod-defined ownership-like
-      concept.
-    * Returns false or nil, if the player is allowed to do such actions.
-    * `name` will be "" for non-players or unknown players.
-    * This function should be overridden by protection mods and should be used
-      to check if a player can interact at a position.
-    * This function should call the old version of itself if the position is
-      not protected by the mod.
+    * Returning `true` restricts the player `name` from modifying (i.e. digging,
+       placing) the node at position `pos`.
+    * `name` will be `""` for non-players or unknown players.
+    * This function should be overridden by protection mods. It is highly
+      recommended to grant access to players with the `protection_bypass` privilege.
+    * Cache and call the old version of this function if the position is
+      not protected by the mod. This will allow using multiple protection mods.
     * Example:
 
           local old_is_protected = minetest.is_protected