aboutsummaryrefslogtreecommitdiff
path: root/advtrains
diff options
context:
space:
mode:
authorY. Wang <yw05@forksworld.de>2022-09-04 17:31:09 +0200
committerY. Wang <yw05@forksworld.de>2022-09-04 17:50:09 +0200
commit49beb106f00d35296c54a6f15cc663526651d376 (patch)
tree21e551a285a4f44960f50082d7ceedab667252d0 /advtrains
parent9a9023bdf8c846661596ba16b125a5ab1102a25a (diff)
downloadadvtrains-49beb106f00d35296c54a6f15cc663526651d376.tar.gz
advtrains-49beb106f00d35296c54a6f15cc663526651d376.tar.bz2
advtrains-49beb106f00d35296c54a6f15cc663526651d376.zip
Use ldoc instead of manpages
Diffstat (limited to 'advtrains')
-rw-r--r--advtrains/atc.lua3
-rw-r--r--advtrains/speed.lua57
-rw-r--r--advtrains/trainlogic.lua6
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