Add basic API documentation

API.md

@@ -0,0 +1,72 @@
+API documentation for Mana 0.2.0
+================================
+
+**Warning:** This API is not considered stable yet.
+Future releases will not enture backwards compability until the
+release of version 1.0.0 of the Mana mod.
+
+
+## Introduction
+The API of the Mana mod allows you to set and receive
+the current and maxiumum mana reserves of a player,
+and to subtract and add mana.
+
+## The basic rules
+For integrity reasons, this mod will ensure that the following assumptions
+are true at all times for all players:
+
+* Current and maximum mana can never be smaller than 0
+* The current value must not be greater than the maximum value
+
+It should be not possible to break these rules using this API alone.
+If you somehow manage to break one ofthe rules, please report a bug.
+
+Furthermore, real numbers may be used as values, but it is not
+recommended.
+
+## Functions
+Of not specified otherwise, all functions return `nil`.
+`playername` always refers to the name of a player, as string.
+`value` always refers to a number.
+
+
+### `mana.set(playername, value)`
+Sets the mana reserve of the specified player to `value`.
+If `value` is smaller than 0, the mana will be set to 0.
+If `value` is greater than the maximum, the mana will be set to the maximum.
+
+
+### `mana.setmax(playername, value)`
+Sets the maximum of the player to `value`.
+
+If the new maximum would become smaller than the current value,
+the current value will automatically be set to
+the new maximum.
+
+
+### `mana.get(playername)`
+Returns the current mana of the specified player as number.
+
+
+### `mana.getmax(playername)`
+Returns the current maximum mana of the specified player as number.
+
+
+### `mana.add(playername, value)`
+Adds the specified amount of mana to the player, but it will be capped
+at the maximum. 
+
+
+#### Return value
+* `true, excess` on success, where `excess` is the amount of Mana which could not be added because it would have exceeded the maximum. `excess` equals `0` if all mana has been added
+* `false` on failure (mana could not be added)
+
+
+
+### `mana.subtract(playername, value)`
+Subtracts the specified amount of mana from the player, but only
+if the player has sufficient mana reservers.
+
+#### Return value
+* `true` on success, all mana has been subtracted
+* `false` on failure, no mana has been subtraceed