Continue writing API documentation, update call signatures for a couple of API functions

mods/ENTITIES/mcl_minecarts/API.md

@@ -1,3 +1,87 @@
+# Table of Contents
+1. Useful Constants
+2. Rail
+3. [Cart functions](#cart-functions)
+4. [Cart-Node Interactions](#cart-node-iteractions)
+
+## Useful Constants
+
+`mcl_minecarts.north`
+`mcl_minecarts.south`
+`mcl_minecarts.east`
+`mcl_minecarts.west`
+
+Human-readable names for the cardinal directions.
+
+## Rail
+
+### Constants
+
+`mcl_minecarts.HORIZONTAL_CURVES_RULES`
+`mcl_minecarts.HORIZONTAL_STANDARD_RULES`
+
+Rail connection rules. Each rule is an table with the following indexes:
+
+1. `node_name_suffix` - The suffix added to a node's `_mcl_minecarts.base_name` to
+   get the name of the node to use for this connection.
+2. `param2_value` - The value of the node's param2. Used to specify rotation.
+
+and the following named options:
+
+- `mask` - Directional connections mask
+- `score` - priority of the rule. If more than one rule matches, the one with the
+  highest store is selected.
+- `can_slope` - true if the result of this rule can be converted into a slope.
+
+### Functions
+
+`mcl_minecarts.get_rail_connections(node_position, options)`
+
+Calculate the rail adjacency information for rail placement. Arguments are:
+
+- `node_position` - the location of the node to calculate adjacency for.
+- `options` - A table containing any of these options:
+  - `legacy`- if true, don't check that a connection proceeds out in a direction
+    a cart can travel. Used for converting legacy rail to newer equivalents.
+  - `ignore_neightbor_connections` - if true, don't check that a cart could leave
+    the neighboring node from this direction.
+
+`mcl_minecarts.update_rail_connections(node_position, options)`
+
+Converts the rail at `node_position`, if possible, another variant (curve, etc.)
+and rotates the node as needed so that rails connect together. `options` is
+passed thru to `mcl_minecarts.get_rail_connections()`
+
+`mcl_minecarts:get_rail_direction(rail_position, cart_direction)`
+
+Returns the next direction a cart traveling in the direction specified in `cart_direction`
+will travel from the rail located at `rail_position`.
+
+## Cart functions <a name='#cart-functions'></a>
+
+`mcl_minecarts.detach_minecart(cart_data)`
+
+This detaches a minecart from any rail it is attached to and makes it start moving
+as an entity affected by gravity. It will keep moving in the same direction and
+at the same speed it was moving at before it detaches.
+
+`mcl_minecarts.get_cart_position(cart_data)`
+
+Compute the location of a minecart from its cart data. This works even when the entity
+is unloaded.
+
+`mcl_minecarts.reverse_cart_direction(cart_data)`
+
+Force a minecart to start moving in the opposite direction of its current direction.
+
+`mcl_minecarts.snap_direction(direction_vector)`
+
+Returns a valid cart movement direction that has the smallest angle between it and `direction_vector`.
+
+`mcl_minecarts:update_cart_orientation(cart)`
+
+Updates the rotation of a cart entity to match the cart's data.
+
 ## Cart-Node interactions
 
 As the cart moves thru the environment, it can interact with the surrounding blocks
@@ -35,10 +119,10 @@ Arguments:
 - `node_definition` - The definition of the node at `node_position`
 
 The available hooks are:
-`_mcl_minecarts.on_enter` - The cart enters this block
+- `_mcl_minecarts.on_enter` - The cart enters this block
-`_mcl_minecarts.on_enter_below` - The cart enters above this block
+- `_mcl_minecarts.on_enter_below` - The cart enters above this block
-`_mcl_minecarts.on_enter_above` - The cart enters below this block
+- `_mcl_minecarts.on_enter_above` - The cart enters below this block
-`_mcl_minecarts.on_enter_side` - The cart enters beside this block
+- `_mcl_minecarts.on_enter_side` - The cart enters beside this block
 
 Only a single function can be installed in each of these handlers. Before installing,
 preserve the existing handler and call it from inside your handler if not `nil`.

mods/ENTITIES/mcl_minecarts/functions.lua

@@ -285,7 +285,7 @@ local function is_ahead_slope(pos, dir)
 	local node_name = force_get_node(below).name
 	return minetest.get_item_group(node_name, "rail_slope") ~= 0
 end
-function mcl_minecarts:get_rail_direction(pos_, dir, ctrl, old_switch, railtype)
+function mcl_minecarts:get_rail_direction(pos_, dir)
 	local pos = vector.round(pos_)
 
 	-- Handle new track types that have track-specific direction handler
@@ -312,7 +312,7 @@ function mcl_minecarts:get_rail_direction(pos_, dir, ctrl, old_switch, railtype)
 
 	return dir
 end
-function mcl_minecarts:update_cart_orientation()
+function mcl_minecarts.update_cart_orientation(self)
 	local staticdata = self._staticdata
 
 	-- constants