From bd3521d4396da91d1b7f5db04b4f618c53965860 Mon Sep 17 00:00:00 2001
From: Hugues Ross <hugues.ross@gmail.com>
Date: Sat, 13 Jun 2020 08:54:13 -0400
Subject: [PATCH] Documentation pass, part 3

---
 table.lua | 28 ++++++++++++++++++++++++++++
 util.lua  |  1 +
 2 files changed, 29 insertions(+)

diff --git a/table.lua b/table.lua
index cd734e2..bb40900 100644
--- a/table.lua
+++ b/table.lua
@@ -1,3 +1,10 @@
+-- Arguments
+-- gui: The GUI API
+-- gui_skin: The GUI skin
+-- audio: The audio playback API
+-- maps: The map API
+-- materials: The material API
+-- map_item: The map item API
 local gui, gui_skin, audio, maps, materials, map_item = ...;
 
 local MAP_SIZE = 40;
@@ -7,8 +14,11 @@ local SCALE_LARGE = 4;
 local SCALE_HUGE = 8;
 
 -- Get the material cost for the given map scale and detail level
+--
 -- scale: The map scale
 -- detail: The detail level
+--
+-- Returns a table with material costs
 local function get_material_cost(scale, detail)
     local paper = scale * 4;
     local pigment = detail * 5;
@@ -30,6 +40,7 @@ local function get_material_cost(scale, detail)
 end
 
 -- Get the material cost of the craft settings from the given table metadata
+--
 -- meta: The metadata to read
 --
 -- Returns a table with the material costs, and a boolean indicating if the
@@ -53,6 +64,7 @@ end
 
 -- Check if the given table metadata has enough materials to cover the given
 -- cost table.
+--
 -- cost: A table of material costs
 -- meta: The metadata
 --
@@ -64,6 +76,7 @@ local function can_afford(cost, meta)
 end
 
 -- Get the material cost of the copy settings from the given table metadata
+--
 -- meta: The metadata to read
 --
 -- Returns a table with the material costs
@@ -90,6 +103,7 @@ end
 local fs = {};
 
 -- Draw a 1px thick horizontal separator formspec element
+--
 -- y: The y position of the separator
 -- skin: A 9-slice background skin table
 --
@@ -106,6 +120,7 @@ function fs.separator(y, skin)
 end
 
 -- Draw all the essential formspec data (size, background, styles, tabs)
+--
 -- w: The width of the formspec
 -- h: The height of the formspec
 -- rank: An into defining the 'rank' of the table being displayed
@@ -217,6 +232,7 @@ function fs.header(w, h, rank, tab, skin)
 end
 
 -- Draw material counters from a table's metadata
+--
 -- x: The x position of the labels
 -- y: The y position of the labels
 -- meta: A metadata object containing the material quantities
@@ -283,6 +299,7 @@ function fs.materials(x, y, meta, skin)
 end
 
 -- Draw a label with material costs from a table
+--
 -- x: The x position of the interface
 -- y: The y position of the interface
 -- cost: A table of material costs, with string keys for the material
@@ -337,6 +354,7 @@ function fs.cost(x, y, cost, skin)
 end
 
 -- Draw the material conversion tab UI
+--
 -- x: The x position of the interface
 -- y: The y position of the interface
 -- pos: The table position (for displaying the inventory)
@@ -379,9 +397,11 @@ function fs.convert(x, y, pos, skin)
 end
 
 -- Draw the map crafting tab UI
+--
 -- x: The x position of the interface
 -- y: The y position of the interface
 -- pos: The table position (for displaying the inventory)
+-- rank: The 'rank' of the table
 -- meta: A metadata object containing the table settings and material
 --       quantities
 -- skin: A formspec skin table
@@ -521,6 +541,7 @@ function fs.craft(x, y, pos, rank, meta, skin)
 end
 
 -- Draw the map copying tab UI
+--
 -- x: The x position of the interface
 -- y: The y position of the interface
 -- pos: The table position (for displaying the inventory)
@@ -570,6 +591,7 @@ function fs.copy(x, y, pos, skin)
 end
 
 -- Draw the player's inventory
+--
 -- x: The x position of the inventory
 -- y: The y position of the inventory
 -- skin: A formspec skin table
@@ -648,6 +670,7 @@ end
 
 -- Called when a player sends input to the server from a formspec
 -- This callback handles player input in the table formspec
+--
 -- player: The player who sent the input
 -- name: The formspec name
 -- fields: A table containing the input
@@ -740,6 +763,7 @@ minetest.register_on_player_receive_fields(function(player, name, fields)
 end);
 
 -- Called after a table is placed. Sets up the table's inventory and metadata.
+--
 -- pos: The node's position
 local function setup_table_node(pos)
     local meta = minetest.get_meta(pos);
@@ -755,6 +779,7 @@ end
 
 -- Called when the player tries to put an item into one of the table's
 -- inventories.
+--
 -- listname: The name of the inventory the item is being placed in.
 -- stack: The itemstack
 --
@@ -774,6 +799,7 @@ end
 
 -- Called when the player tries to move an item between two of the table's
 -- inventories.
+--
 -- to_list: The name of the inventory the item is being placed in.
 -- count: The number of items being moved
 --
@@ -788,6 +814,7 @@ local function table_can_move(_, _, _, to_list, _, count, _)
 end
 
 -- Called when a change occurs in a table's inventory
+--
 -- pos: The node's position
 -- listname: The name of the changed inventory list
 local function table_on_items_changed(pos, listname, _, _, _)
@@ -801,6 +828,7 @@ local function table_on_items_changed(pos, listname, _, _, _)
     end
 end
 
+-- The table node definitions
 minetest.register_node("cartographer:simple_table", {
     description = "Shabby Cartographer's Table",
     drawtype = "mesh",
diff --git a/util.lua b/util.lua
index c760a07..26a21ea 100644
--- a/util.lua
+++ b/util.lua
@@ -1,5 +1,6 @@
 return {
     -- Get an entry from a list for a given detail level
+    --
     -- textures: An array of textures
     -- detail: The detail level
     --