Improve comments all over the place

README.md

@@ -1,16 +1,11 @@
 # Example mod for the Help modpack (`doc`, `doc_items`, etc.)
-This mod is for modders and useless for anyone else.
+This mod is for modders who want to learn how to use the APIs of the mods
+`doc`, `doc_items` and `doc_identifier` from the Help modpack.
+It is useless for anyone else. This mod should only be used for testing
+and not in production.
+
 It demonstrates the usage of the APIs of the Help mods. This should help you
 in getting started with this modpack.
-This example mod does not demonstrate everything, only the most
-frequently-needed features to help you get started. For most use cases, this
-knowledge might already suffice. You do not need to understand everything to
-use this modpack.
-Read `API.md` of the respective mods to learn how to use the Help mods
-properly.
-
-Using the APIs of the Help modpack helps to improve the overall quality
-and completeness of the entire help.
 
 This mod includes examples for the following mods:
 
@@ -22,6 +17,15 @@ This mod includes examples for the following mods:
          This is rather heavy stuff, intended for advanced modding.
          But is also very flexible.
 
+This example mod only shows the most frequently-needed features to help
+you get started. For most use cases, this knowledge might already
+suffice. You do not need to understand everything to use this modpack.
+Read `API.md` of the respective mods to learn how to use the Help mods
+properly.
+
+Using the APIs of the Help modpack helps to improve the overall quality
+and completeness of the entire help.
+
 Activate this mod in your world to see some example categories, entries and
 items added.
 

doc.lua

@@ -1,26 +1,26 @@
 --[[ 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.
+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, and to use some utility
+functions.
 
 This example demonstrates how to add categories and how to add entries into them.
-It also demonstrates the versatility of the very important `build_formspec` field of
-categories.
-]]
+It also demonstrates the versatility of the very important `build_formspec`
+function used in category definitions. ]]
 
--- Let's start with a very simple text-based category
--- This category only contains simple text
+-- Let's start with a very simple text-based category.
+-- This category only contains simple text.
 doc.new_category("example1", {
-	-- This is for humans and mandatory
-	name = "Text Example",
+	-- This name is for humans and mandatory
+	name = "Text Examples",
 	-- This category uses a preset formspec builder for 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. We add 2 entries
+-- Entries for the aforementioned category. We add 2 entries.
 doc.new_entry("example1", "text", {
-	-- This is for the entry title in the user interface, it's mandatory
+	-- This is for the entry title in the user interface, it's mandatory.
 	name = "Text example",
 	-- 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.",
@@ -29,14 +29,14 @@ doc.new_entry("example1", "text", {
 -- We will use this entry in doc_identifier.lua
 doc.new_entry("example1", "entity", {
 	name = "Entity entry",
-	data = "This is the entry for the entity (added in doc_identifier.lua). The example entity is just a boring cube which floats in the air. Punch it to destroy it.",
+	data = "This is the entry for the entity (added in doc_identifier.lua). The example entity is just a simple cube which floats in the air. Punch it to destroy it.",
 })
 
 -------------------------------------------------------------------------------
 
 --[[ Category with hidden entry.
-This is a category like the one before, but this time, we add one entry
-which starts hidden. ]]
+This is a category like the one before, but this time, we add a hidden entry.
+]]
 doc.new_category("example_hide", {
 	name = "Example Hidden",
 	build_formspec = doc.entry_builders.text
@@ -59,10 +59,11 @@ minetest.register_chatcommand("doc_example_reveal", {
 	func = function(playername, params)
 		-- This reveals the previously created entry
 		doc.mark_entry_as_revealed(playername, "example_hide", "hidden")
+
 		minetest.chat_send_player(playername, "The hidden doc_example entry has been revealed! Look into the category “Example Hidden” to see it.")
 	end,
 })
---[[ In actual game, you would probably want to invent more engaging ways to
+--[[ In actual games, you would probably want to invent more engaging ways to
 reveal entries. ;-) ]]
 
 -------------------------------------------------------------------------------
@@ -72,14 +73,15 @@ function to display entry data dynamically. ]]
 doc.new_category("example2", {
 	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
+	--[[ 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 ]]
+	--[[ ADVANCED: Sorting example ]]
 	--[[ The entry data includes population as a number. This means we could (if we
 	want to) define a custom sorting function. This affects the order of the entries.
 	It makes sure that in the list of entries, the city with the highest population
@@ -137,12 +139,12 @@ doc.new_category("example3", {
 doc.new_entry("example3", "simple", {
 	name="Label",
 	-- Please note the coordinates are shoddily chosen here.
-	-- FIXME: Show how to properly align widgets
+	-- TODO: Show how to properly align widgets
 	data = "label[5,5;Just a label.]"
 })
 doc.new_entry("example3", "widgets", {
 	name="Widget Chaos",
-	-- Just some meaningless widgets for demonstration purposes
+	-- Just some chaotic meaningless widgets for demonstration purposes
 	data = "label[0,1;Label]label[0,2;Label 2]button[0,3;3,1;example_ignored;Button]textlist[0,4;4,4;example_ignored2;A,B,C,D;]scrollbar[4,1;2,0.2;horizontal;example_ignored3;0]",
 })
 doc.new_entry("example3", "testbutton", {

doc_identifier.lua

@@ -1,6 +1,6 @@
 -- Example for using doc_identifier (Lookup Tool)
--- NOTE: Use the API to make custom entities identifiable by the lookup tool.
--- If you do not define any custom entities, using the API is not needed.
+-- Reminder: Use the API to make custom entities identifiable by the lookup tool.
+-- If you do not define any custom entities, you don't need this API.
 -- This example adds one example entity and adds doc_identifier support for it.
 
 -- To spawn this entity, use the chat command “/spawnentity doc_example:entity”
@@ -17,10 +17,12 @@ minetest.register_entity("doc_example:entity", {
 	hp_max = 1,
 })
 
---[[ This is the actual code you need to add doc_identifier support.
-The following code means, whenever you use the lookup tool on the example
-entity, the entry “entity” in category “example1” will be shown. ]]
+-- This is the actual code you need to add doc_identifier support.
 doc.sub.identifier.register_object("doc_example:entity", "example1", "entity")
 
+--[[ Yes, this is all you need!
+The code means, whenever you use the lookup tool on the example
+entity, the entry “entity” in category “example1” will be shown. ]]
+
 --[[ NOTE: If you don't do this, the lookup tool will show an error message
 when you use it on this entity. ]]

doc_items.lua

@@ -63,6 +63,8 @@ doc.sub.items.register_factoid("craftitems", "groups", function(category_id, def
 		return string.format("Example factoid: This item is member of the example group at rating %d.",
 				def.groups.example)
 	else
+		--[[ It is legal to return an empty string. In that case, nothing,
+		not even an empty line, will be added. ]]
 		return ""
 	end
 end)