Update examples on doc

doc.lua

@@ -1,44 +1,76 @@
--- Very simple text-based category
--- This category contains entries with
+--[[ Example for Documentation System [`doc`].
+Reminder This mod is the core of the Help modpack. It is thus rather low-level.
+Use this to add your very own categories and entries.
+
+This example demonstrates how to add categories and how to add entries into them.
+It also demonstrates the versality of the very important `build_formspec` field of
+categories.
+]]
+
+-- Let's start with a very simple text-based category
+-- This category only contains simple
 doc.new_category("example1", {
+	-- This is for humans and mandatory
 	name = "Text Example",
 	-- This category uses a preset formspec builder for displaying simple text
 	build_formspec = doc.entry_builders.text
+	-- Reminder: build_formspec determines how the entry data will be presented to the user
 })
 
--- Entry for the aforementioned category
+-- Entry for the aforementioned category. We only add 1 entry
 doc.new_entry("example1", "text", {
+	-- This is for humans and mandatory
 	name = "Text example",
-	-- For this category, the data is simply the text to be displayed
+	-- For this category, the entry data is simply the text to be displayed
 	data = "Lorem Minetest dolor sit amet. Bla bla bla bla Minetest bla bla bla bla Mese bla. Bla bla bla bla bla, celeron55 bla bla, bla.",
 })
 
--- Category with hidden entry
+-------------------------------------------------------------------------------
+
+-- Category with hidden entry.
+-- This is a category like the one before, but this time, we add one entry which starts hidden
 doc.new_category("example_hide", {
 	name = "Example Hidden",
 	build_formspec = doc.entry_builders.text
 })
 
-doc.new_entry("example_hide", "hidden" {
+-- This entry will start hidden. The user will not see it until it gets revealed by using
+-- `doc.mark_entry_as_revealed`.
+-- TODO: Add example for that, too
+doc.new_entry("example_hide", "hidden", {
 	name = "Hidden Entry",
-	hidden = true
+	hidden = true,
 	data = "This entry is hidden.",
 })
 
---[[ A simple category with 3 entries: Cities ]]
+-------------------------------------------------------------------------------
+--[[ A simple category with 3 entries: Cities.
+Now we're getting somewhere! This time, we define a custom build_formspec function to display
+entry data dynamically. ]]
 doc.new_category("example2", {
-	name="Example: Cities",
-	description="Example category: Quick information about the cities of the world",
+	name = "Example: Cities",
+	description = "Example category: Quick information about the cities of the world",
 	-- This is a manual formspec builder: This will parse the entry data and turns it into nice formspec widgets
+	-- Reminder: We MUST return a valid formspec string
 	build_formspec = function(data)
 		return	"label[0,1;Description: "..minetest.formspec_escape(data.description).."]" ..
 			"label[0,2;Population: "..data.population.."]"
 	end,
+
+	--[[ Sorting example ]]
+	-- The entry data includes population as a number. This means we could (if we want to) define a custom sorting functino
+	--[[ This affects the order of the entries. It makes sure that in the list of entries, the city with the highest population
+	comes first. Custom sorting is entirely optional but it might make it easier for the user to navigate. But note that the
+	default alphabetical sorting is often good enough. ]]
+	sorting = "function",
+	sorting_data = function(entry1, entry2)
+		return entry1.data.population > entry2.data.population
+	end,
 })
 
 doc.new_entry("example2", "london", {
 	name="London",
-	-- This data are then put into the previous build_formspec
+	-- Reminder: This data is put into the previous build_formspec function
 	data = {
 		description = "London is the capital of the United Kingdom.",
 		population = 8538689,
@@ -59,17 +91,26 @@ doc.new_entry("example2", "tripoli", {
 	},
 })
 
---[[ Formspec category: This category shows how you can use widgets in entries to interact with them ]]
+-------------------------------------------------------------------------------
+--[[ Formspec category: This category shows how you can add widgets in entries and even interact with them ]]
 doc.new_category("example3", {
 	name="Example: Formspec",
 	description="Example category for manual freeform formspec entries",
-	-- This category uses one of the formspec entries
+	-- This is a built-in formspec builder. In this case, the entry data is expected
+	-- to contains the full formspec definition for any entry. This is useful if you want
+	-- to build every entry by hand. The downside is that it doesn't allow for dynamic entries.
 	build_formspec = doc.entry_builders.formspec,
+
+	--[[ Sorting example ]]
+	-- This demonstates the custom sorting type. In the entry list, the entries will appear in the exact order as specified
+	sorting = "custom",
+	sorting_data = { "simple", "widgets", "testbutton" },
 })
 
 doc.new_entry("example3", "simple", {
 	name="Label",
-	-- For the formspec type being used, the data is the raw formspec data
+	-- Please note the coordinates are shoddily chosen here.
+	-- FIXME: Show how to properly align widgets
 	data = "label[5,5;Just a label.]"
 })
 doc.new_entry("example3", "widgets", {
@@ -83,7 +124,8 @@ doc.new_entry("example3", "testbutton", {
 	data = "button[2,2;3,1;example_button;Event]",
 })
 
--- … and here we react on the event by writing something into the chat
+-- … and here we react on the button event by writing something into the chat
+-- This demonstrates how you can use an entry widget for custom actions
 minetest.register_on_player_receive_fields(function(player, formname, fields)
 	-- Condition 1: This checks if the player is even using the entry tab. This check is always the same
 	if formname == "doc:entry" then
@@ -100,6 +142,7 @@ minetest.register_on_player_receive_fields(function(player, formname, fields)
 	end
 end)
 
+-------------------------------------------------------------------------------
 --[[ This category shows off the gallery widget ]]
 doc.new_category("example4", {
 	name="Example: Galleries",
@@ -114,6 +157,7 @@ doc.new_category("example4", {
 -- Several gallery entries
 doc.new_entry("example4", "gallery2", {
 	name="Gallery with 2 images",
+	-- The entry data will be also fed into `doc_widgets_gallery`
 	data = {{image="default_grass.png"}, {image="default_book.png"}},
 })
 

doc_items.lua

@@ -32,7 +32,7 @@ minetest.register_tool("doc_example:tool", {
 	-- 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!"),
+		minetest.chat_send_all("The doc_example chat tool has been used!")
 	end,
 })