Correct documentation around minetest.item_place

The code that calls minetest.item_place_object was removed
in 2013 in commit fc61c8809b9a1d47d9f117446764107a56cec956.

diff --git a/builtin/game/item.lua b/builtin/game/item.lua
index 8041d557e4b7492b35b8c5da2b911afac02a6cf7..00c1912fc254b9a6fb0dda76dae02e2a4b8c3436 100644 (file)
--- a/builtin/game/item.lua
+++ b/builtin/game/item.lua
@@ -398,6 +398,7 @@ function core.item_place_node(itemstack, placer, pointed_thing, param2,
        return itemstack, true
 end
 
+-- deprecated, item_place does not call this
 function core.item_place_object(itemstack, placer, pointed_thing)
        local pos = core.get_pointed_thing_position(pointed_thing, true)
        if pos ~= nil then
@@ -419,6 +420,7 @@ function core.item_place(itemstack, placer, pointed_thing, param2)
                end
        end
 
+       -- Place if node, otherwise do nothing
        if itemstack:get_definition().type == "node" then
                return core.item_place_node(itemstack, placer, pointed_thing, param2)
        end

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index cb92ea7b85c3f63e9e0ea2f070ba73dfce3128df..ca59aad958db41bea2c84052e640e6ace5c8968f 100644 (file)
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -4851,10 +4851,8 @@ Rollback
     * Revert latest actions of someone
     * `actor`: `"player:<name>"`, also `"liquid"`.
 
-Defaults for the `on_*` item definition functions
--------------------------------------------------
-
-These functions return the leftover itemstack.
+Defaults for the `on_place` and `on_drop` item definition functions
+-------------------------------------------------------------------
 
 * `minetest.item_place_node(itemstack, placer, pointed_thing[, param2, prevent_after_place])`
     * Place item as a node
@@ -4864,20 +4862,23 @@ These functions return the leftover itemstack.
     * returns `itemstack, success`
 * `minetest.item_place_object(itemstack, placer, pointed_thing)`
     * Place item as-is
-* `minetest.item_place(itemstack, placer, pointed_thing, param2)`
-    * Use one of the above based on what the item is.
+    * returns the leftover itemstack
+    * **Note**: This function is deprecated and will never be called.
+* `minetest.item_place(itemstack, placer, pointed_thing[, param2])`
+    * Wrapper that calls `minetest.item_place_node` if appropriate
     * Calls `on_rightclick` of `pointed_thing.under` if defined instead
     * **Note**: is not called when wielded item overrides `on_place`
-    * `param2` overrides `facedir` and wallmounted `param2`
+    * `param2` overrides facedir and wallmounted `param2`
     * returns `itemstack, success`
 * `minetest.item_drop(itemstack, dropper, pos)`
     * Drop the item
-* `minetest.item_eat(hp_change, replace_with_item)`
-    * Eat the item.
+    * returns the leftover itemstack
+* `minetest.item_eat(hp_change[, replace_with_item])`
+    * Returns `function(itemstack, user, pointed_thing)` as a
+      function wrapper for `minetest.do_item_eat`.
     * `replace_with_item` is the itemstring which is added to the inventory.
       If the player is eating a stack, then replace_with_item goes to a
-      different spot. Can be `nil`
-    * See `minetest.do_item_eat`
+      different spot.
 
 Defaults for the `on_punch` and `on_dig` node definition callbacks
 ------------------------------------------------------------------