From db1c3c10b8ed97931a2fa462d19ee6d47c5eacb9 Mon Sep 17 00:00:00 2001 From: SmallJoker Date: Wed, 5 Oct 2022 21:07:41 +0200 Subject: [PATCH] API doc: use Minetest style --- doc/mod_api.txt | 94 ++++++++++++++++++++++--------------------------- 1 file changed, 42 insertions(+), 52 deletions(-) diff --git a/doc/mod_api.txt b/doc/mod_api.txt index ef87697..99fa638 100644 --- a/doc/mod_api.txt +++ b/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")