--[[ This is the doc_items example.
This example shows how to add help texts to items and how to use
other frequently-used features of doc_items.
]]

--[[ IMPORTANT REMINDER: doc_items mod will automatically generate help
entries for all items (a few exceptions apply) without your intervention.
doc_items already extracts a lot of item definition automatically.
The API is mainly concernd about enhancing the existing item entries.

Hint: When using this example, use the `/help_reveal`
chat command to reveal all item entries (for testing) ]]

--[[ 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.",
	-- The tool entry will be visible for everyone at start
	_doc_items_hidden = false,
	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)

-- 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)