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

2 files changed, 9 insertions, 16 deletions

diff --git a/builtin/game/item.lua b/builtin/game/item.lua
index ced28771e..7855880f8 100644
--- 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 b25c4ec9d..2650bfedf 100644
--- 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