Improve documentation of mcl_autogroup

API.md

@@ -17,6 +17,10 @@ Items can have these fields:
    anvil.
    See `mcl_banners` for an example.
 
+Tools can have these fields:
+* `_mcl_autogroup_groupcaps`: Specifies the digging groups that a tool can dig
+  and how efficiently.  See `_mcl_autogroup` for more information.
+
 All nodes can have these fields:
 
 * `_mcl_hardness`: Hardness of the block, ranges from 0 to infinity (represented by -1). Determines digging times. Default: 0

mods/CORE/_mcl_autogroup/init.lua

@@ -16,32 +16,46 @@ information.
 How the mod is used
 ===================
 
-In MineClone 2, all diggable node have the hardness set in the custom field
+In MineClone 2, all diggable nodes have the hardness set in the custom field
-"_mcl_hardness" (0 by default).  Digging groups are registered using the
+"_mcl_hardness" (0 by default).  These values are used together with digging
-following code:
+groups by this mod to create the correct digging times for nodes.  Digging
+groups are registered using the following code:
 
+    mcl_autogroup.register_diggroup("shovely")
     mcl_autogroup.register_diggroup("pickaxey", {
         levels = { "wood", "gold", "stone", "iron", "diamond" }
     })
-    mcl_autogroup.register_diggroup("shovely")
-    mcl_autogroup.register_diggroup("shovely")
 
-The first line registers "pickaxey" as a digging group.  The "levels" field
+The first line registers a simple digging group.  The second line registers a
-indicates that the digging group have 5 levels (in this case one for each
+digging group with 5 different levels (in this case one for each material of a
-material of a pickaxe).  The second line registers "shovely" as a digging group
+pickaxes).
-which does not have separate levels (if the "levels" field is not set it
-defaults to 0).
 
 Nodes indicate that they belong to a particular digging group by being member of
 the digging group in their node definition.  "mcl_core:dirt" for example has
 shovely=1 in its groups.  If the digging group has multiple levels the value of
 the group indicates which digging level the node requires.
 "mcl_core:stone_with_gold" for example has pickaxey=4 because it requires a
-pickaxe of level 4 ("stone") to be mined.
+pickaxe of level 4 be mined.
 
-For tools to be able to dig nodes of the digging groups they need to use the
+For tools to be able to dig nodes of digging groups they need to use the have
-have the custom field "_mcl_autogroup_groupcaps" function to get the groupcaps.
+the custom field "_mcl_autogroup_groupcaps" function to get the groupcaps.  The
-See "mcl_tools/init.lua" for examples of this.
+value of this field is a table which defines which groups the tool can dig and
+how efficiently.
+
+    _mcl_autogroup_groupcaps = {
+        handy = { tool_multiplier = 1, level = 1, uses = 0 },
+        pickaxey = { tool_multiplier = 1, level = 0, uses = 0 },
+    }
+
+The "uses" field indicate how many uses (0 for infinite) a tool has when used on
+the specified digging group.  The "tool_multiplier" field is a multiplier to the
+dig speed on that digging group.
+
+The "level" field indicates which levels of the group the tool can harvest.  A
+level of 0 means that the tool cannot harvest blocks of that node.  A level of 1
+or above means that the tool can harvest nodes with that level or below.  See
+"mcl_tools/init.lua" for examples on how "_mcl_autogroup_groupcaps" is used in
+practice.
 
 Information about the mod
 =========================
@@ -123,9 +137,8 @@ end
 -- group - the group which it is digging
 -- can_harvest - if the tool can harvest the block
 -- tool_multiplier - dig speed multiplier for tool (default 1)
--- efficiency - efficiency level for the tool (default 0)
+-- efficiency - efficiency level for the tool if applicable
 local function get_digtimes(group, can_harvest, tool_multiplier, efficiency)
-	efficiency = efficiency or 0
 	tool_multiplier = tool_multiplier or 1
 	speed_multiplier = tool_multiplier
 	if efficiency then
@@ -162,6 +175,8 @@ local function get_groupcap(group, can_harvest, multiplier, efficiency, uses)
 	}
 end
 
+-- Add the groupcaps from a field in "_mcl_autogroup_groupcaps" to the groupcaps
+-- of a tool.
 local function add_groupcaps(groupcaps, groupcaps_def, efficiency)
 	for g, capsdef in pairs(groupcaps_def) do
 		local mult = capsdef.tool_multiplier or 1

mods/CORE/mcl_autogroup/init.lua

@@ -1,6 +1,7 @@
 --[[
-This mod implements the API to register digging groups for mcl_autogroup.  The
+This is one part of a mod to replicate the digging times from Minecraft.  This
-rest of the mod is implemented and documented in the mod _mcl_autogroup.
+part only exposes a function to register digging groups.  The rest of the mod is
+implemented and documented in the _mcl_autogroup.
 
 The mod is split up into two parts, mcl_autogroup and _mcl_autogroup.
 mcl_autogroup contains the API functions used to register custom digging groups.
@@ -18,9 +19,8 @@ mcl_autogroup.registered_diggroups = {}
 -- def - Table with information about the diggroup (defaults to {} if unspecified)
 --
 -- Values in def:
--- level - If this value is unspecified then the group does not have
+-- level - If specified it is an array containing the names of the different
---         levels, otherwise it is an array containing the names of the
+--         digging levels the digging group supports.
---         different digging levels the digging group supports.
 function mcl_autogroup.register_diggroup(group, def)
 	mcl_autogroup.registered_diggroups[group] = def or {}
 end