API doc: use Minetest style

doc/mod_api.txt

@@ -1,7 +1,8 @@
 unified_inventory API
 =====================
 
-This file provides information about the API of unified_inventory.
+This file provides information about the API of unified_inventory
+and can be viewed in Markdown readers.
 
 API revisions within unified_inventory can be checked using:
 
@@ -163,68 +164,57 @@ Register a non-standard craft recipe:
 Categories
 ----------
 
-Register a new category:
-	The config table (second argument) is optional, and all its members are optional
-	See the unified_inventory.set_category_* functions for more details on the members of the config table
+ * `unified_inventory.register_category(name, def)`
+     * Registers a new category
+     * `name` (string): internal category name
+     * `def` (optional, table): also its fields are optional
 
 	unified_inventory.register_category("category_name", {
-		symbol = "mod_name:item_name" or "texture.png",
+		symbol = source,
+		-- ^ Can be in the format "mod_name:item_name" or "texture.png",
 		label = "Human Readable Label",
 		index = 5,
+		-- ^ Categories are sorted by index. Lower numbers appear before higher ones.
+		--   By default, the name is translated to a number: AA -> 0.0101, ZZ -> 0.2626
+		---  Predefined category indices: "all" = -2, "uncategorized" = -1
 		items = {
 			"mod_name:item_name",
 			"another_mod:different_item"
 		}
+		-- ^ List of items within this category
 	})
+ * `unified_inventory.remove_category(name)`
+     * Removes an entire category
 
-Add / override the symbol for a category:
-	The category does not need to exist first
-	The symbol can be an item name or a texture image
-	If unset this will default to "default:stick"
+Modifier functions (to be removed)
 
-	unified_inventory.set_category_symbol("category_name", "mod_name:item_name" or "texture.png")
+ * `unified_inventory.set_category_symbol(name, source)`
+     * Changes the symbol of the category. The category does not need to exist yet.
+     * `name` (string): internal category name
+     * `source` (string, optional): `"mod_name:item_name"` or `"texture.png"`.
+       Defaults to `"default:stick"` if not specified.
+ * `unified_inventory.set_category_label(name, label)`
+     * Changes the human readable label of the category.
+     * `name` (string): internal category name
+     * `label` (string): human readable label. Defaults to the category name.
+ * `unified_inventory.set_category_index(name, index)`
+     * Changes the sorting index of the category.
+     * `name` (string): internal category name
+     * `index` (numeric): any real number
 
-Add / override the human readable label for a category:
-	If unset this will default to the category name
+Item management
 
-	unified_inventory.set_category_label("category_name", "Human Readable Label")
+ * `	unified_inventory.add_category_item(name, itemname)`
+     * Adds a single item to the category
+     * `itemname` (string): self-explanatory
+ * `unified_inventory.add_category_items(name, { itemname1, itemname2, ... }`
+     * Same as above but with multiple items
+ * `unified_inventory.remove_category_item(name, itemname)`
+     * Removes an item from the category
+ * `unified_inventory.find_category(itemname)`
+     * Looks up the first category containing this item
+     * Returns: category name (string) or nil
+ * `unified_inventory.find_categories(itemname)`
+     * Looks up the item name within all registered categories
+     * Returns: array of category names (table)
 
-Add / override the sorting index of the category:
-	Must be a number, can also be negative (-5) or fractional (2.345)
-	This determines the position the category appears in the list of categories
-	The "all" meta-category has index -2, the "misc"/"uncategorized" meta-category has index -1, use a negative number smaller than these to make a category appear before these in the list
-	By default categories are sorted alphabetically with an index between 0.0101(AA) and 0.2626(ZZ)
-
-	unified_inventory.set_category_index("category_name", 5)
-
-Add a single item to a category:
-
-	unified_inventory.add_category_item("category_name", "mod_name:item_name")
-
-Add multiple items to a category:
-
-	unified_inventory.add_category_items("category_name", {
-		"mod_name:item_name",
-		"another_mod:different_item"
-	})
-
-Remove an item from a category:
-
-	unified_inventory.remove_category_item("category_name", "mod_name:item_name")
-
-Remove a category entirely:
-
-	unified_inventory.remove_category("category_name")
-
-Finding existing items in categories:
-	This will find the first category an item exists in
-	It should be used for checking if an item is catgorised
-	Returns "category_name" or nil
-
-	unified_inventory.find_category("mod_name:item_name")
-
-
-	This will find all the categories an item exists in
-	Returns a number indexed table (list) of category names
-
-	unified_inventory.find_categories("mod_name:item_name")