Use ldoc instead of manpages

3 files changed, 61 insertions, 5 deletions

diff --git a/advtrains/atc.lua b/advtrains/atc.lua
index c1ff218..d3eea4f 100644
--- a/advtrains/atc.lua
+++ b/advtrains/atc.lua
@@ -128,7 +128,8 @@ advtrains.atc_function = function(def, preset, suffix, rotation)
 				local meta=minetest.get_meta(pos)
 				if meta then
 					if not fields.save then 
-						--[[--maybe only the dropdown changed
+						--[[
+						--maybe only the dropdown changed
 						if fields.mode then
 							meta:set_string("mode", idxtrans[fields.mode])
 							if fields.mode=="digiline" then
diff --git a/advtrains/speed.lua b/advtrains/speed.lua
index ec4f928..b77b22b 100644
--- a/advtrains/speed.lua
+++ b/advtrains/speed.lua
@@ -1,5 +1,17 @@
--- auxiliary functions for the reworked speed restriction system
+--- Auxiliary functions for the reworked speed restriction system.
+-- For this library, the speed limit may be represented using
+--
+-- * A non-negative number representing a speed limit in m/s
+-- * `-1` or `nil`, which lifts the speed limit
+--
+-- The use of other values (in particular, `nan` and `inf`) may result in undefined behavior.
+--
+-- Please note the difference between the meaning of `nil` in this library and in signal aspect tables.
 
+--- Check if `a` is more strict than `b`
+-- @function lessp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_lessp(a, b)
 	if not a or a == -1 then
 		return false
@@ -10,26 +22,50 @@ local function s_lessp(a, b)
 	end
 end
 
+--- Check if `a` is less strict than `b`
+-- @function greaterp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_greaterp(a, b)
 	return s_lessp(b, a)
 end
 
+--- Check if `a` is not more strict than `b`
+-- @function not_lessp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_not_lessp(a, b)
 	return not s_lessp(a, b)
 end
 
+--- Check if `a` is not less strict than `b`
+-- @function not_greaterp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_not_greaterp(a, b)
 	return not s_greaterp(a, b)
 end
 
+--- Check if `a` and `b` represent equivalent speed limits
+-- @function equalp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_equalp(a, b)
 	return (a or -1) == (b or -1)
 end
 
+--- Check if `a` and `b` do not represent equivalent speed limits
+-- @function not_equalp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_not_equalp(a, b)
 	return (a or -1) ~= (b or -1)
 end
 
+--- Returns the speed limit that is less strict
+-- @function max
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_max(a, b)
 	if s_lessp(a, b) then
 		return b
@@ -38,6 +74,10 @@ local function s_max(a, b)
 	end
 end
 
+--- Returns the speed limit that is more strict
+-- @function min
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_min(a, b)
 	if s_lessp(a, b) then
 		return a
@@ -46,6 +86,8 @@ local function s_min(a, b)
 	end
 end
 
+--- Returns the strictest speed limit in a table
+-- @param tbl a table of speed limits
 local function get_speed_restriction_from_table (tbl)
 	local strictest = -1
 	for _, v in pairs(tbl) do
@@ -57,6 +99,10 @@ local function get_speed_restriction_from_table (tbl)
 	return strictest
 end
 
+--- Update a value in the speed limit table
+-- @param tbl the `speed_restriction` field of a train table
+-- @param rtype the type of speed limit
+-- @param rval the speed limit of the given type
 local function set_speed_restriction (tbl, rtype, rval)
 	if rval then
 		tbl[rtype or "main"] = rval
@@ -64,12 +110,21 @@ local function set_speed_restriction (tbl, rtype, rval)
 	return tbl
 end
 
+--- Set the speed limit of a train
+-- @function set_restriction
+-- @param train the train object
+-- @param rtype the type of speed limit
+-- @param rval the speed limit of the given type
 local function set_speed_restriction_for_train (train, rtype, rval)
 	local t = train.speed_restrictions_t or {main = train.speed_restriction}
 	train.speed_restrictions_t = set_speed_restriction(t, rtype, rval)
 	train.speed_restriction = get_speed_restriction_from_table(t)
 end
 
+--- Set the speed limit of a train based on a signal aspect
+-- @function merge_aspect
+-- @param train the train object
+-- @param asp the signal aspect table
 local function merge_speed_restriction_from_aspect_to_train (train, asp)
 	return set_speed_restriction_for_train(train, asp.type, asp.main)
 end
diff --git a/advtrains/trainlogic.lua b/advtrains/trainlogic.lua
index 35c3726..ac1424b 100644
--- a/advtrains/trainlogic.lua
+++ b/advtrains/trainlogic.lua
@@ -562,7 +562,7 @@ function advtrains.train_step_b(id, train, dtime)
 		train.acceleration = 0
 	end
 	
-	--- 3b. if braking, modify the velocity BEFORE the movement
+	--- 3b. if braking, modify the velocity BEFORE the movement ---
 	if braking then
 		local dv = advtrains.get_acceleration(train, lever) * dtime
 		local v1 = v0 + dv
@@ -671,7 +671,7 @@ function advtrains.train_step_b(id, train, dtime)
 	recalc_end_index(train)
 	--atprint("in train_step_b: New index",train.index,"end",train.end_index,"vel",train.velocity)
 	
-	--- 4a. if accelerating, modify the velocity AFTER the movement
+	--- 4a. if accelerating, modify the velocity AFTER the movement ---
 	if accelerating then
 		local dv = advtrains.get_acceleration(train, lever) * dtime
 		local v1 = v0 + dv
@@ -715,7 +715,7 @@ function advtrains.train_step_c(id, train, dtime)
 	local train_moves=(train.velocity~=0)
 	local very_short_train = train.trainlen < 3
 
-	--- On-track collision handling - detected in train_step_b, but handled here so all other train movements have already happened.
+	-- On-track collision handling - detected in train_step_b, but handled here so all other train movements have already happened. --
 	if train.ontrack_collision_info then
 		train.velocity = 0
 		train.acceleration = 0