From f3b28df6ccf06f48f702136c4e8a6ab4f89ccbc7 Mon Sep 17 00:00:00 2001 From: kabou Date: Sat, 2 Apr 2022 00:39:36 +0200 Subject: [PATCH] Rework function comments. * Move descriptive function comments to above the function definition. * Adopt some luadoc styles. * Update a stale reference to a renamed function in comments. --- mods/ITEMS/mcl_composters/init.lua | 65 ++++++++++++++++++------------ 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/mods/ITEMS/mcl_composters/init.lua b/mods/ITEMS/mcl_composters/init.lua index 53f8757bbc..56422d8b5e 100644 --- a/mods/ITEMS/mcl_composters/init.lua +++ b/mods/ITEMS/mcl_composters/init.lua @@ -48,12 +48,18 @@ local vector_offset = vector.offset local is_protected = minetest.is_protected local record_protection_violation = minetest.record_protection_violation +--- Fill the composter when rightclicked. +-- +-- `on_rightclick` handler for composter blocks of all fill levels except +-- for the "ready" composter (see: composter_harvest). +-- If the item used on the composter block is compostable, there is a chance +-- that the level of the composter may increase, depending on the value of +-- compostability of the item. +-- +-- parameters are the standard parameters passed to `on_rightclick`. +-- returns the remaining itemstack. +-- local function composter_add_item(pos, node, player, itemstack, pointed_thing) - -- - -- handler for filling the composter when rightclicked - -- - -- as an on_rightclick handler, it returns an itemstack - -- if not player or (player:get_player_control() and player:get_player_control().sneak) then return itemstack end @@ -97,24 +103,31 @@ local function composter_add_item(pos, node, player, itemstack, pointed_thing) return itemstack end +--- Update a full composter block to ready for harvesting. +-- +-- `on_timer` handler. The timer is set in function 'composter_add_item' +-- when the composter level has reached 7. +-- +-- pos: position of the composter block. +-- returns false, thereby cancelling further activity of the timer. +-- local function composter_ready(pos) - -- - -- update the composter block to ready for harvesting - -- this function is a node callback on_timer. - -- the timer is set in function 'composter_fill' when composter level is 7 - -- - -- returns false in order to cancel further activity of the timer - -- swap_node(pos, {name = "mcl_composters:composter_ready"}) -- maybe spawn particles again? -- TODO: play some sounds return false end +--- Spawn bone meal item and reset composter block. +-- +-- `on_rightclick` handler for the "ready" composter block. Causes a +-- bone meal item to be spawned from the composter and resets the +-- composter block to an empty composter block. +-- +-- parameterss are the standard parameters passed to `on_rightclick`. +-- returns itemstack (unchanged in this function). +-- local function composter_harvest(pos, node, player, itemstack, pointed_thing) - -- - -- handler for harvesting bone meal from a ready composter when rightclicked - -- if not player or (player:get_player_control() and player:get_player_control().sneak) then return itemstack end @@ -131,10 +144,12 @@ local function composter_harvest(pos, node, player, itemstack, pointed_thing) return itemstack end +--- Construct composter nodeboxes with varying levels of compost. +-- +-- level: compost level in the composter +-- returns a nodebox definition table. +-- local function composter_get_nodeboxes(level) - -- - -- Convenience function to construct the nodeboxes for varying levels of compost - -- local top_y_tbl = {[0]=-7, -5, -3, -1, 1, 3, 5, 7} local top_y = top_y_tbl[level] / 16 return { @@ -149,9 +164,9 @@ local function composter_get_nodeboxes(level) } end +--- Register empty composter node. -- --- Register empty composter node --- This is the base model that is craftable and can be placed in an inventory +-- This is the craftable base model that can be placed in an inventory. -- minetest.register_node("mcl_composters:composter", { description = composter_description, @@ -179,9 +194,9 @@ minetest.register_node("mcl_composters:composter", { on_rightclick = composter_add_item }) +--- Template function for composters with compost. -- --- Template function for composters with compost --- For each fill level a custom node is registered +-- For each fill level a custom node is registered. -- local function register_filled_composter(level) local id = "mcl_composters:composter_"..level @@ -219,15 +234,13 @@ local function register_filled_composter(level) end end --- --- Register filled composters (7 levels) +--- Register filled composters (7 levels). -- for level = 1, 7 do register_filled_composter(level) end --- --- Register composter ready to be harvested +--- Register composter that is ready to be harvested. -- minetest.register_node("mcl_composters:composter_ready", { description = S("Composter") .. "(" .. S("ready for harvest") .. ")",