Add more example items

doc_items.lua

@@ -1,21 +1,66 @@
-doc.sub.items.register_factoid("nodes", "damage", function(id)
-	return "FACTOID: damage."
+-- Example to enhance the documentation for your items
+
+--[[ HELP TEXTS ]]
+
+-- For nontrivial items, you typically want to use the _doc_items_* fields
+minetest.register_craftitem("doc_example:item1", {
+	description = "doc_example test item 1",
+	-- This is the typical way to add extended item descriptions.
+	_doc_items_longdesc = "This is an useless example item. It does nothing.",
+	-- This simple item is self-explanatory, so we can omit _doc_items_usagehelp
+	-- For more fields, see API.md of doc_items
+
+	-- Just an example group
+	group = { example = 1 },
+})
+
+-- These are just more example items which we use for the factoids later
+minetest.register_craftitem("doc_example:item2", {
+	description = "doc_example test item 2",
+	group = { example = 2 },
+})
+
+minetest.register_craftitem("doc_example:item3", {
+	description = "doc_example test item 3",
+	group = { example = 25 },
+})
+
+minetest.register_tool("doc_example:tool", {
+	description = "doc_example chat tool",
+	_doc_items_longdesc = "This tool is able to write something into the chat.",
+	-- This tool has an unique non-standard use (i.e. not mining, not melee combat, etc.), so we should add this field as well
+	-- Read API.md of doc_items for guidelines to write good help texts
+	_doc_items_usagehelp = "Punch to send a chat message.",
+	on_punch = function()
+		minetest.chat_send_all("The doc_example chat tool has been used!"),
+	end,
+})
+
+--[[ FACTOIDS
+	Reminder: A factoid is an automatically generated text based on the item definition.
+	This section will demonstrate the use of factoids
+]]
+
+-- This adds an automatically generated text for all items which are a member of the example group
+doc.sub.items.register_factoid("craftitems", "groups", function(category_id, def)
+	if def.groups.example then
+		return string.format("Example factoid: This item is member of the example group at rating %d.", def.groups.example)
+	else
+		return ""
+	end
 end)
-doc.sub.items.register_factoid("nodes", "movement", function(id)
-	return "FACTOID: movement."
+
+-- This factoid adds the drawtype for nodes
+doc.sub.items.register_factoid("nodes", "misc", function(category_id, def)
+	return string.format("Example factoid: This item has the drawtype “%s”.", def.drawtype)
 end)
-doc.sub.items.register_factoid("nodes", "sound", function(id)
-	return "FACTOID: sound."
+
+-- This factoid adds the drawtype for nodes
+doc.sub.items.register_factoid("nodes", "misc", function(category_id, def)
+	return string.format("Example factoid: This item has the drawtype “%s”.", def.drawtype)
 end)
-doc.sub.items.register_factoid("nodes", "gravity", function(id)
-	return "FACTOID: gravity."
-end)
-doc.sub.items.register_factoid("nodes", "drop_destroy", function(id)
-	return "FACTOID: drop_destroy."
-end)
-doc.sub.items.register_factoid("nodes", "light", function(id)
-	return "FACTOID: light."
-end)
-doc.sub.items.register_factoid("nodes", "mining", function(id)
-	return "FACTOID: mining."
+
+-- This factoid adds the drawtype for nodes
+doc.sub.items.register_factoid("nodes", "misc", function(category_id, def)
+	return string.format("Example factoid: This item has the drawtype “%s”.", def.drawtype)
 end)