Add API documentation

API.md

@@ -0,0 +1,146 @@
+# API documentation for version 0.2.0
+## Core principles
+As a modder, you are free to write basically about everything and are also
+relatively free in the presentation of information. The Documentation
+System has no restrictions on content whatsoever.
+
+In the documentation system, everything is built on categories and entries.
+An entry is a single piece of documentation and is the basis of all actual
+documentation. Categories group multiple entries of the same topic together.
+
+Categories also define a template which is used to determine how the final
+result in the Entry tab looks like. Entries themselves have a data field
+attached to them, this is a table containing arbitrary metadata which is
+used to construct the final formspec which is used on the Entry tab.
+
+## Possible use cases
+I present to you some possible use cases to give you a rough idea what
+this mod is capable and how certain use casescould be implemented.
+
+### Simple use case: Minetest basics
+I want to write in freeform short help texts about the basic concepts of
+Minetest or my subgame. First I define a category called “Basics”, the data
+for each of its entry is just a freeform text. The template function simply
+creates a formspec where this freeform text is displayed.
+
+### Complex use case: Blocks
+I could create a category called “Blocks”, and this category is supposed to
+contain entries for every single block in the game. For this case, a freeform 
+approach would be very inefficient and error-prone, as a lot of data can be
+reused.
+
+Here the template function comes in handy: The internal entry data
+contain a lot of different things about a block, like block name, identifier,
+custom description and most importantly, the definition table of the block.
+
+Finally, the template function takes all that data and turns it into
+sentences which are just concatenated, telling as many useful facts about
+this block as possible.
+
+## Functions
+This is a list of all publicly available functions.
+
+### `doc.new_category(id, def)`
+Adds a new category. You have to define an unique identifier, a name
+and a template function to build the entry formspec from the entry
+data.
+
+#### Parameters
+* `id`: Unique category identifier as a string
+* `def`: Definition table, it has the following fields:
+    * `name`: Category name to be shown in the interface
+    * `build_formspec`: The template function. Takes entry data as its
+      only parameter (has the data type of the entry data) and must
+      return a formspec which is inserted in the Entry tab.
+
+#### Return value
+Always `nil`.
+
+### `doc.new_entry(category_id, entry_id, def)`
+Adds a new entry into an existing category. You have to define the category
+to which to insert the entry, the entry's identifier, a name and some
+data which defines the entry. Note you do not directly define here how the
+end result of an entry looks like, this is done by `build_formspec` from
+the category definition.
+
+#### Parameters
+* `category_id`: Identifier of the category to add the entry into
+* `entry_id`: Unique identifier of the new entry, as a string
+* `def`: Definition table, it has the following fields:
+    * `name`: Entry name to be shown in the interface
+    * `data`: Arbitrary data attached to the entry. Any data type is allowed;
+      The data in this field will be used to create the actual formspec
+      with `build_formspec` from the category definition
+
+#### Return value
+Always `nil`.
+
+### `function doc.show_doc(playername)`
+Opens the main documentation formspec for the player (Main tab).
+
+#### Parameters
+* `playername`: Name of the player to show the formspec to
+
+### `doc.show_category(playername, category_id)`
+Opens the documentation formspec for the player at the specified category
+(Category tab).
+
+#### Parameters
+* `playername`: Name of the player to show the formspec to
+* `category_id`: Category identifier of the selected category
+
+#### Return value
+Always `nil`.
+
+### `doc.show_entry(playername, category_id, entry_id)`
+Opens the documentation formspec for the player showing the specified entry
+of a category (Entry tab).
+
+#### Parameters
+* `playername`: Name of the player to show the formspec to
+* `category_id`: Category identifier of the selected category
+* `entry_id`: Entry identifier of the entry to show
+
+#### Return value
+Always `nil`.
+
+### `doc.entry_exists(category_id, entry_id)`
+Checks if the specified entry exists and returns `true` or `false`.
+
+#### Parameters
+* `category_id`: Category identifier of the category to check
+* `entry_id`: Entry identifier of the entry to check for its existance
+
+#### Return value
+Returns `true` if and only if:
+
+* The specified category exists
+* This category contains the specified entry
+
+Otherwise, returns `false`.
+
+### `doc.add_entry_alias(category_id, entry_id, alias)`
+Adds a single alias for an entry. When an entry has an alias, attempting to open
+an entry by an alias name results in opening the entry of the original name.
+Aliases are true within one category only.
+
+#### Parameters
+* `category_id`: Category identifier of the category of the entry in question
+* `entry_id`: Entry identifier of the entry to create an alias for
+* `alias`: Alias (string) for `entry_id`
+
+#### Return value
+Always `nil`.
+
+### `doc.add_entry_aliases(category_id, entry_id, aliases)`
+Adds an arbitrary amount of aliases for an entry at once. Apart from that, this
+function has the same effect as `doc.add_entry_alias`.
+
+#### Parameters
+* `category_id`: Category identifier of the category of the entry in question
+* `entry_id`: Entry identifier of the entry to create aliases for
+* `aliases`: Table/list of aliases (strings) for `entry_id`
+
+#### Return value
+Always `nil`.
+