Improve Lua API documentation

Changes:
  * Add extra documentation for remove_item.

    This isn't as silly as it sounds: iterate a list containing items with
    unique metadata each, and remove_item the first one you find, placing
    into a different - fine, except the remove will invariably remove the
    wrong one, leading to items being duplicated and others destroyed.

    Arguably it's a bug, and Inventory::removeItem should actually remove
    the item you tell it to. (i.e. if the passed ItemStack has metadata,
    match it). But it seems reasonable to just document the behaviour
    more clearly.

 * Improve string_to_pos documentation.
 * Clarify dig_node documentation (return value).
 * Better on_step documentation.
 * get_nodemeta -> get_meta.
 * Other minor fixes.
This commit is contained in:
Ciaran Gultnieks 2014-03-17 20:05:35 +00:00 committed by ShadowNinja
parent 2b1a151226
commit c30346ea30

@ -1303,7 +1303,7 @@ string:trim()
minetest.pos_to_string({x=X,y=Y,z=Z}) -> "(X,Y,Z)"
^ Convert position to a printable string
minetest.string_to_pos(string) -> position
^ Same but in reverse
^ Same but in reverse. Returns nil if the string can't be parsed to a position.
minetest.formspec_escape(string) -> string
^ escapes characters [ ] \ , ; that can not be used in formspecs
minetest.is_yes(arg)
@ -1505,6 +1505,7 @@ minetest.place_node(pos, node)
^ Place node with the same effects that a player would cause
minetest.dig_node(pos)
^ Dig node with the same effects that a player would cause
Returns true if successful, false on failure (e.g. protected location)
minetest.punch_node(pos)
^ Punch node with the same effects that a player would cause
@ -1885,7 +1886,7 @@ Class reference
----------------
NodeMetaRef: Node metadata - reference extra data and functionality stored
in a node
- Can be gotten via minetest.get_nodemeta(pos)
- Can be gotten via minetest.get_meta(pos)
methods:
- set_string(name, value)
- get_string(name)
@ -2052,8 +2053,11 @@ methods:
can be fully added to the list
- contains_item(listname, stack): returns true if the stack of items
can be fully taken from the list
remove_item(listname, stack): take as many items as specified from the list,
returns the items that were actually removed (as an ItemStack)
- remove_item(listname, stack): take as many items as specified from the list,
returns the items that were actually removed (as an ItemStack) - note that
any item metadata is ignored, so attempting to remove a specific unique
item this way will likely remove the wrong one - to do that use set_stack
with an empty ItemStack
- get_location() -> location compatible to minetest.get_inventory(location)
-> {type="undefined"} in case location is not known
@ -2224,7 +2228,9 @@ Registered entities
- on_activate(self, staticdata)
^ Called when the object is instantiated.
- on_step(self, dtime)
^ Called on every server tick (dtime is usually 0.1 seconds)
^ Called on every server tick, after movement and collision processing.
dtime is usually 0.1 seconds, as per the dedicated_server_step setting
in minetest.conf.
- on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
^ Called when somebody punches the object.
^ Note that you probably want to handle most punches using the