Add API doc

1 files changed, 295 insertions, 0 deletions

diff --git a/API.md b/API.md
new file mode 100644
index 0000000..72babaf
--- /dev/null
+++ b/API.md
@@ -0,0 +1,295 @@
+# API documentation for `doc_items` (Version 0.3.0)
+## Introduction
+This document explains the API of `doc_items`. It contains a reference of
+all functions.
+
+***Warning***: This mod is still in alpha stage, expect bugs and missing
+features!
+
+## Quick start
+A common use case for using this API requires only to set some hand-written
+help texts for a few items.
+
+To add your description and/or usage help to items, optionally depend on
+`doc_items`, use the functions `doc.sub.items.set_items_longdesc` and
+`doc.sub.items.set_items_usagehelp` in the following programming idiom:
+
+    if minetest.get_modpath("doc_items") ~= nil then
+        doc.sub.items.set_items.longdesc({
+            ["example:item1"] = "Long description goes here.",
+            ["example:item2"] = "Lour long description goes here.",
+        })
+        doc.sub.items.set_items.usagehelp({
+            ["example:item1"] = "Describe here how this item can be used.",
+            ["example:item2"] = "Describe here how this item can be used.",
+        })
+    end
+
+Don't forget to read at least the documentation of these functions.
+
+If you need more customization, read ahead. ;-)
+
+## Concepts
+### Factoids
+Basically, a factoid is usually a single sentence telling the player a specific
+fact about the item. The task of each factoid is to basically convert parts
+of the item definition to useful, readable, understandable text.
+
+Example: It's a fact that `default:sand` has the group `falling_node=1`.
+A factoid for this is basically just a simple conditional which puts the
+the sentence “This block is affectet to gravity and can fall.” into the
+text if the node is member of said group.
+
+Factoids can be more complex than that. The factoid for node drops needs to
+account for different drop types and probabilities, etc.
+
+`doc_items` has many predefined factoids already. This includes all “special”
+groups (like `falling_node`), drops, mining capabilities, punch interval,
+and much more.
+
+Custom factoids can be added with `doc.sub.items.register_factoid`.
+
+The idea behind factoids is to generate as much information as possible
+automatically to reduce reduncancy, inconsistencs and the workload of hand-
+written descriptions.
+
+### Long description and usage help
+Factoids are not always sufficient to describe an item. This is the case
+for facts where the item definition can not be used to automatically
+generate texts. Examples: Custom formspecs, ABMs, special tool action
+on rightclick.
+
+That's where the long description and usage help comes into play.
+Those are two texts which are written manually for a specific item.
+
+Roughly, the long description is for describing **what** the item is, how it
+acts, what it is for. The usage help is for explaining **how** the
+item can be used but it is not needed for standard mining tools and weapons.
+
+For more information, read the recommendations for
+`doc.sub.items.set_items_longdesc` and `doc.sub.items.set_items_usagehelp`.
+
+### Forced and suppressed items
+By default, an entry for each item is added, except for items in the group
+`not_in_creative_inventory`. This default behaviour already covers most
+useful items, but it still sometimes needs tweaking.
+
+Entries can be forced, which means they will be forcefully added, against the
+default behaviour. Entries can be suppressed which means they will not
+be added at all.
+
+The default behaviour can be overridden by two ways: Groups and a funciton call.
+
+Use groups when you can directly define an item (in other words, in **your**
+mods).
+
+To force the entry of an items, add the item to the group `in_doc = 1`.
+To suppress the entry of an item, add the item to the group `not_in_doc = 1`.
+
+There is also the function `doc.sub.items.add_forced_item_entries` which
+forces entries for a number of entries. You should **only** use this function
+when you can not use groups.
+
+When there are contradictions, forcing a group takes precedence over suppressing
+a group.
+
+#### Example
+Think of a node which is supposed to be indestructible. Because such a node is
+quite dangerous in Creative Mode, it has been added to the
+`not_in_creative_inventory` group. However, documentation of this node is
+obviously required, so the entry for this node needs to be **forced**.
+
+## Functions
+This is the reference of all available functions in this API.
+
+### `doc.sub.items.set_items_longdesc(longdesc_table)`
+Sets the long description of items. `longdesc_table` is
+a table where the keys are the itemstrings and the values
+are the the description strings for each item.
+
+The long description of an item is a manually written text
+to describe a particular item.
+
+#### Default long descriptions
+`doc_items` registers two long descriptions by default: For air
+and the hand (default tool).
+It is possible to overwrite each of them, just call the funcion
+as usual.
+
+The hand description is kept very generic, but it might miss
+some information on more complex subgames. In this case, the hand's
+long description might need overwriting.
+
+#### Recommendations
+The long description should roughly contain the following info:
+
+* What the item does
+* What it is good for
+* How it may be generated in the world
+* Maybe some background info if you're in a funny mood
+* Notable information which does't fit elsewhere
+
+The desciption should normally **not** contain:
+
+* Information which is already covered by factoids, like digging groups,
+  damage, group memberships, etc.
+* How the item can be used
+* Direct information about other items
+* Any other redundant information
+* Crafting recipes
+
+One exception from the rule may be for highlighting the most important
+purpose of a simple item, like that coal lumps are primarily used as fuel.
+
+Sometimes, a long description is not neccessary because the item is already
+exhaustively explained by factoids.
+
+Minimal style guide: Use complete sentences.
+
+#### Example
+    doc.sub.items.set_items_longdesc({
+         ["example:painter"] = "Paints blocks.",
+         ["example:flower"] = "Likes to grow on grass when it is near water.",
+    })
+
+### `doc.sub.items.set_items_usagehelp(usagehelp_table)`
+Sets the usage help texts of items. The function is completely analog
+to `doc.sub.items.set_items_longdesc` and has the same syntax, it
+only differs in semantics.
+
+The usage help is supposed to describe how the item can be used.
+
+#### Example
+    doc.sub.items.set_items_usagehelp({
+         ["example:painter"] = "Punch any block to paint it red.",
+    })
+
+#### Recommendations
+The usage help should only be set for items which are in some way special
+in their usage. Standard tools and weapons should never have an usage help.
+
+The rule of thumb is this: If a new player who already knows the Minetest
+basics, but not this item, will not direcly know how to use this item,
+then the usage help should be added. If basic Minetest knowledge or
+existing factoids are completely sufficient, usage help should not be added.
+
+The recommendations for what not to put into the usage help is the same
+as for long descriptions.
+
+### `doc.sub.items.register_factoid(category_id, factoid_type, factoid_generator)`
+***Note***: This function not fully implemented. It currently supports only
+factoids for nodes.
+
+Add a custom factoid (see above) for the specified category.
+
+* `category_id`: The documentation category fow which the factoid applies:
+    * `"nodes"`: Blocks
+    * `"tools"`: Tools and weapons (***Not yet supported***)
+    * `"craftitems"`: Misc. items (***Not yet supported***)
+* `factoid_type`: Rough categorization of the factoid's content. Controls
+  where in the text the factoid appears. Possible values:
+    * `"groups"`: Factoid appears near groups
+    * **(more to come)**
+* `factoid_generator`: A function which turns item definition into a string
+  (see blow)
+
+#### `factoid_generator(itemstring, def)`
+`itemstring` is the itemstring of the item to be documented, and `def` is the
+complete item definition table (from Minetest).
+
+This function must return a helpful string which turns a part of the item's
+definition into an useful sentence or text. The text can contain newlines,
+but it must not end with a newline.
+
+This function must **always** return a string. If you don't want to add any text,
+return the empty string.
+
+Style guide: Try to use complete sentences and avoid too many newlines.
+
+#### Example
+This factoid will add the sentence “This block will extinguish nearby fire.”
+to all blocks which are member of the group `puts_out_fire`.
+
+    doc.sub.items.register_factoid("nodes", "groups", function(itemstring, def)
+        if def.groups.puts_out_fire ~= nil then
+            return "This block will extinguish nearby fire."
+        else
+            return ""
+        end
+    end)
+
+### `doc.sub.items.add_real_group_names(groupnames)`
+Use this function so set some more readable group names to show them
+in the formspec, since the internal group names are somewhat cryptic
+to players.
+
+`groupnames` is a table where the keys are the “internal” group names and
+the values are the group names which will be actually shown in the
+Documentation System.
+
+***Note***: This function is mostly there to work around a problem in
+Minetest as it does not support “real” group names, which means exposing
+groups to an interface is not pretty. Therefore, this function may be
+deprecated when Minetest supports such a thing.
+
+### `doc.sub.items.add_notable_groups(groupnames)`
+Add a list of groups you think are notable enough to be mentioned in the
+“This item belongs to the following groups: (…)” factoid.
+
+`groupnames` is a table of group names.
+
+By default, no groups are shown for this factoid which means this factoid
+is never displayed.
+
+What is “notable” is subjective, but here's a rule of thumb you may follow:
+
+You should add groups with this function if:
+
+* This group is used for crafting purposes
+* This group is somehow important for interaction
+* This group appears in `connect_to` definitions of nodes
+
+Do not add groups if:
+
+* The group is only used internally
+* The group is unteresting for the player
+* A factoid covering this group already exists
+* Writing a factoid would be more useful
+* The group is a mining or damage group
+* Rating is important to gameplay (consider writing a factoid instead)
+
+The intention of this function is to give a short rundown of the groups
+which are notable as they are important to gameplay in some way yet don't
+deserve a full-blown factoid.
+
+### `doc.sub.items.add_forced_item_entries(itemstrings)`
+Adds items which will be forced to be added to the entry list, even if
+the item is not in creative inventory.
+
+`itemstrings` is a table of itemstrings of items to force the entries for.
+
+***Note***: The recommended way to force item entries is by adding the item
+to the group `in_doc=1` (see above). Only use this function when you can
+not use groups.
+
+### `doc.sub.items.add_item_name_overrides(itemstrings)`
+Overrides the entry names of entries to the provided names. By default,
+each entry name equals the item's `description` field.
+
+`itemstrings` is a table in which the keys are itemstrings and the values
+are the entry titles you want to use for those items.
+
+#### Preset overrides
+The following item name overrides are defined by default:
+
+    { [""] = "Hand", 
+      ["air"] = "Air" }
+
+It is possible to override **these** names, just use the function normally.
+
+#### Example
+    doc.sub.items.add_item_name_overrides({
+        ["air"] = "Air", -- original description: “Air (You hacker you!)”
+        ["farming:wheat_8"] = "Wheat Plant", -- Item description was empty
+        ["example:node"] = "My Custom Name",
+    })