Documentation pass, part 1

- Also added more optional parameters to the gui api

audio.lua

@@ -1,5 +1,9 @@
+-- Audio API (Internal)
+--
+-- Contains functions for providing audio feedback
 local audio = {
     -- Play a feedback sound localized on the given player
+    --
     -- sound: The sound to play
     -- player: The player who triggered the sound
     play_feedback = function(sound, player)

autofill.lua

@@ -1,3 +1,7 @@
+-- Arguments
+-- chunk: The chunk coordinate conversion API
+-- scanner: The map scanning API
+-- maps: The map API
 local chunk, scanner, maps = ...;
 
 -- Periodically-called function to fill in maps and queue chunks for manual

biome_api.lua

@@ -1,9 +1,13 @@
+-- Arguments
+-- util: API for uncategorized utility methods
 local util = ...;
 
 local biome_lookup = {};
 
+-- Contains functions for registering and getting biome-related mapping information
 return {
     -- Register a biome with textures to display
+    --
     -- name: A string containing the biome name
     -- textures: A table of texture names.
     --           These should correspond with detail levels,
@@ -20,9 +24,11 @@ return {
     end,
 
     -- Get the texture name (minus index/extension) for the given biome, height, and detail level.
+    --
     -- name: A string containing the biome name
     -- height: A number representing the Y position of the biome
     -- detail: The detail level
+    --
     -- Returns a string with a texture name, or nil if no matching biome entry was found.
     get_texture = function (name, height, detail)
         for _,biome in ipairs(biome_lookup) do

commands.lua

@@ -1,3 +1,7 @@
+-- Arguments
+-- chunk: The chunk coordinate conversion API
+-- audio: The audio playback API
+-- map_formspec: The map display API
 local chunk, audio, map_formspec = ...;
 
 local MAXINT = 2147483647;

formspec.lua

@@ -1,5 +1,19 @@
-local gui = {};
+-- Gui API (Internal)
+--
+-- Contains functions for building formspec-based uis
+local gui = {
+};
 
+-- Create a formspec
+--
+-- w: The width of the window
+-- h: The height of the window
+-- (Optional) version: The formspec version. Defaults to 3.
+-- (Optional) bg: A 9-slice background skin object
+-- Additional arguments are added as additional formspec elements
+--
+-- Returns a table. Calling table.concat on the result will produce
+-- a usable formspec string.
 function gui.formspec(args)
     local data = string.format("formspec_version[%d] size[%f,%f]", args.version or 3, args.w, args.h);
 
@@ -17,51 +31,129 @@ function gui.formspec(args)
     return data;
 end
 
+-- Create an animated image formspec element
+--
+-- animation: An animation skin object
+-- (Optional) x: The x position of the element. Defaults to 0.
+-- (Optional) y: The y position of the element. Defaults to 0.
+-- (Optional) w: The width of the element. Defaults to 1.
+-- (Optional) h: The height of the element. Defaults to 1.
+-- (Optional) size: Multiplies the width and height. Defaults to 1.
+-- (Optional) id: The element id
+--
+-- Returns a formspec string
 function gui.animated_image(args)
+    local x = args.x or 0;
+    local y = args.y or 0;
+    local w = args.w or 1 * (args.size or 1);
+    local h = args.h or 1 * (args.size or 1);
+
     return string.format("animated_image[%f,%f;%f,%f;%s;%s;%d;%d]",
-                         args.x, args.y,
+                         x, y,
-                         args.w, args.h,
+                         w, h,
                          args.id or "",
                          args.animation.texture .. ".png",
                          args.animation.frame_count,
                          args.animation.frame_duration);
 end
 
+-- Create a 9-slice background formspec element
+--
+-- skin: A 9-slice background skin object
+-- (Optional) x: The x position of the element. Defaults to 0.
+-- (Optional) y: The y position of the element. Defaults to 0.
+-- (Optional) w: The width of the element. Defaults to 1.
+-- (Optional) h: The height of the element. Defaults to 1.
+-- (Optional) size: Multiplies the width and height. Defaults to 1.
+-- (Optional) fullsize: Whether or not to fill the parent formspec. Defaults to false.
+--
+-- Returns a formspec string
 function gui.bg9(args)
+    local x = args.x or 0;
+    local y = args.y or 0;
+    local w = args.w or 1 * (args.size or 1);
+    local h = args.h or 1 * (args.size or 1);
+
     return string.format("background9[%f,%f;%f,%f;%s;%s;%s]",
-                          args.x or 0, args.y or 0,
+                          x, y,
-                          args.w or 1 * (args.size or 1), args.h or 1 * (args.size or 1),
+                          w, h,
                           args.skin.texture .. ".png",
                           args.fullsize or false,
                           tostring(args.skin.radius));
 end
 
+-- Create a button formspec element
+--
+-- (Optional) text: The text to display on the button
+-- (Optional) x: The x position of the element. Defaults to 0.
+-- (Optional) y: The y position of the element. Defaults to 0.
+-- (Optional) w: The width of the element. Defaults to 1.
+-- (Optional) h: The height of the element. Defaults to 1.
+-- (Optional) size: Multiplies the width and height. Defaults to 1.
+-- (Optional) id: The element id
+-- (Optional) tooltip: The tooltip to display when hovering this element.
+-- (Optional) disabled: Replaces the id with "disabled_button", allowing it to
+--                      receive a specific style
+--
+-- Returns a formspec string
 function gui.button(args)
+    local x = args.x or 0;
+    local y = args.y or 0;
+    local w = args.w or 1 * (args.size or 1);
+    local h = args.h or 1 * (args.size or 1);
+
     if args.disabled then
-        return string.format("button[%f,%f;%f,%f;disabled_button;%s]", args.x, args.y, args.w, args.h, args.text);
+        return string.format("button[%f,%f;%f,%f;disabled_button;%s]", x, y, w, h, args.text or "");
     end
 
-    local data = string.format("button[%f,%f;%f,%f;%s;%s]", args.x, args.y, args.w, args.h, args.id, args.text);
+    local data = string.format("button[%f,%f;%f,%f;%s;%s]", x, y, w, h, args.id or "", args.text or "");
 
     if args.tooltip then
-        data = data .. gui.tooltip {
+        if args.id and not args.disabled then
-            id = args.id,
+            data = data .. gui.tooltip {
-            text = args.tooltip
+                id = args.id,
-        };
+                text = args.tooltip
+            };
+        else
+            data = data .. gui.tooltip {
+                x = x,
+                y = y,
+                w = w,
+                h = h,
+                text = args.tooltip
+            };
+        end
     end
 
     return data;
 end
 
+-- Create a formspec container
+--
+-- (Optional) x: The x offset of the container. Defaults to 0.
+-- (Optional) y: The y offset of the container. Defaults to 0.
+-- (Optional) w: The width of the container (for drawing a background). Defaults to 1.
+-- (Optional) h: The height of the container (for drawing a background). Defaults to 1.
+-- (Optional) size: Multiplies the width and height. Defaults to 1.
+-- (Optional) bg: A 9-slice background skin object
+--
+-- Additional arguments are added as the container's child elements
+--
+-- Returns a formspec string
 function gui.container(args)
-    local data = string.format("container[%f,%f]", args.x, args.y);
+    local x = args.x or 0;
+    local y = args.y or 0;
+    local w = args.w or 1 * (args.size or 1);
+    local h = args.h or 1 * (args.size or 1);
+
+    local data = string.format("container[%f,%f]", x, y);
 
     if args.bg then
         data = data .. gui.bg9 {
             x = 0,
             y = 0,
-            w = args.w,
+            w = w,
-            h = args.h,
+            h = h,
 
             skin = args.bg,
         };
@@ -74,28 +166,93 @@ function gui.container(args)
     return data .. "container_end[]";
 end
 
+-- Create an image formspec element
+--
+-- image: The image to display.
+-- (Optional) x: The x offset of the container. Defaults to 0.
+-- (Optional) y: The y offset of the container. Defaults to 0.
+-- (Optional) w: The width of the container (for drawing a background). Defaults to 1.
+-- (Optional) h: The height of the container (for drawing a background). Defaults to 1.
+-- (Optional) size: Multiplies the width and height. Defaults to 1.
+--
+-- Returns a formspec string
 function gui.image(args)
-    return string.format("image[%f,%f;%f,%f;%s]", args.x, args.y, args.w, args.h, args.image);
+    local x = args.x or 0;
+    local y = args.y or 0;
+    local w = args.w or 1 * (args.size or 1);
+    local h = args.h or 1 * (args.size or 1);
+
+    return string.format("image[%f,%f;%f,%f;%s]", x, y, w, h, args.image);
 end
 
+-- Create an image button formspec element
+--
+-- image: The image to display on the button
+-- (Optional) text: The text to display on the button
+-- (Optional) x: The x position of the element. Defaults to 0.
+-- (Optional) y: The y position of the element. Defaults to 0.
+-- (Optional) w: The width of the element. Defaults to 1.
+-- (Optional) h: The height of the element. Defaults to 1.
+-- (Optional) size: Multiplies the width and height. Defaults to 1.
+-- (Optional) id: The element id
+-- (Optional) tooltip: The tooltip to display when hovering this element.
+-- (Optional) disabled: Replaces the id with "disabled_button", allowing it to
+--                      receive a specific style
+--
+-- Returns a formspec string
 function gui.image_button(args)
+    local x = args.x or 0;
+    local y = args.y or 0;
+    local w = args.w or 1 * (args.size or 1);
+    local h = args.h or 1 * (args.size or 1);
+
+    if args.disabled then
+        return string.format("image_button[%f,%f;%f,%f;%s;disabled_button;%s]",
+                              x, y,
+                              w, h,
+                              args.image,
+                              args.text or "");
+    end
+
     local data = string.format("image_button[%f,%f;%f,%f;%s;%s;%s]",
-                                args.x, args.y,
+                                x, y,
-                                args.w, args.h,
+                                w, h,
                                 args.image,
-                                args.id,
+                                args.id or "",
                                 args.text or "");
 
     if args.tooltip then
-        data = data .. gui.tooltip {
+        if args.id and not args.disabled then
-            id = args.id,
+            data = data .. gui.tooltip {
-            text = args.tooltip
+                id = args.id,
-        };
+                text = args.tooltip
+            };
+        else
+            data = data .. gui.tooltip {
+                x = x,
+                y = y,
+                w = w,
+                h = h,
+                text = args.tooltip
+            };
+        end
     end
 
     return data;
 end
 
+-- Create an inventory list formspec element
+--
+-- location: The location of the inventory
+-- id: The id of the inventory list
+-- w: The number of columns in the inventory list
+-- h: The number of rows in the inventory list
+-- (Optional) x: The x position of the element. Defaults to 0.
+-- (Optional) y: The y position of the element. Defaults to 0.
+-- (Optional) bg: A 9-slice background skin object (To display under each slot)
+-- (Optional) tooltip: The tooltip to display when hovering this element.
+--
+-- Returns a formspec string
 function gui.inventory(args)
     local data = "";
 
@@ -112,7 +269,10 @@ function gui.inventory(args)
         end
     end
 
-    data = data .. string.format("list[%s;%s;%f,%f;%f,%f;]", args.location, args.id, args.x, args.y, args.w, args.h);
+    data = data .. string.format("list[%s;%s;%f,%f;%f,%f;]",
+                                  args.location, args.id,
+                                  args.x or 0, args.y or 0,
+                                  args.w, args.h);
 
     if args.tooltip then
         data = data .. gui.tooltip {
@@ -127,19 +287,27 @@ function gui.inventory(args)
     return data;
 end
 
+-- Create a label formspec element
+--
+-- text: The text of the label
+-- (Optional) textcolor: The color of the label
+-- (Optional) x: The x position of the element. Defaults to 0.
+-- (Optional) y: The y position of the element. Defaults to 0.
+--
+-- Returns a formspec string
 function gui.label(args)
     if args.textcolor then
         return string.format("label[%f,%f;%s%s]",
-                             args.x,
+                             args.x or 0,
-                             args.y,
+                             args.y or 0,
                              minetest.get_color_escape_sequence(args.textcolor),
                              args.text);
     end
 
-    return string.format("label[%f,%f;%s]", args.x, args.y, args.text);
+    return string.format("label[%f,%f;%s]", args.x or 0, args.y or 0, args.text);
 end
 
-function gui.style_internal(selector, properties)
+local function style_internal(selector, properties)
     local data = "[" .. selector;
     for name,value in pairs(properties) do
         data = data .. string.format(";%s=%s", name, tostring(value));
@@ -147,14 +315,37 @@ function gui.style_internal(selector, properties)
     return data .. "]";
 end
 
+-- Create a formspec style
+--
+-- selector: A valid comma-separated list of id-based style selectors
+-- properties: A table of property names and values
+--
+-- Returns a formspec string
 function gui.style(args)
-    return "style" .. gui.style_internal(args.selector, args.properties);
+    return "style" .. style_internal(args.selector, args.properties);
 end
 
+-- Create a formspec style
+--
+-- selector: A valid comma-separated list of type-based style selectors
+-- properties: A table of property names and values
+--
+-- Returns a formspec string
 function gui.style_type(args)
-    return "style_type" .. gui.style_internal(args.selector, args.properties);
+    return "style_type" .. style_internal(args.selector, args.properties);
 end
 
+-- Create a formspec tooltip element
+--
+-- text: The text of the tooltip
+-- (Optional) id: The ID of the element to display on
+--
+-- (Required when id == nil) x: The x position of the element
+-- (Required when id == nil) y: The y position of the element
+-- (Required when id == nil) w: The width of the element
+-- (Required when id == nil) h: The height of the element
+--
+-- Returns a formspec string
 function gui.tooltip(args)
     if args.id then
         return string.format("tooltip[%s;%s]", args.id, args.text);

map_formspec.lua

@@ -27,6 +27,7 @@ local function map_get_marker(map, x, y)
 end
 
 -- Get the variant of the tile at a given position
+--
 -- prefix: The part of the tile texture name before the variant
 -- x: The X position of the tile (in map coordinates)
 -- z: The Z position of the tile (in map coordinates)
@@ -38,6 +39,7 @@ local function get_variant(prefix, x, z, noise)
 end
 
 -- Generate formspec markup for a given map
+--
 -- x: The X position of the map (in map coordinates)
 -- y: The Z position of the map (in map coordinates)
 -- w: The width of the map (in map coordinates)
@@ -157,6 +159,7 @@ end
 local map_formspec = {};
 
 -- Get the formspec for a given map segment
+--
 -- x: The X position of the map, in map coordinates
 -- y: The Y position of the map, in map coordinates
 -- w: The width of the map, in map coordinates
@@ -179,6 +182,7 @@ function map_formspec.from_coords(x, y, w, h, detail, scale, height_mode)
 end
 
 -- Get the formspec for a given map table
+--
 -- map: The map to use
 -- x: The X position of the player marker, in map coordinates
 -- y: The Y position of the player marker, in map coordinates