From 49beb106f00d35296c54a6f15cc663526651d376 Mon Sep 17 00:00:00 2001 From: "Y. Wang" Date: Sun, 4 Sep 2022 17:31:09 +0200 Subject: Use ldoc instead of manpages --- advtrains/atc.lua | 3 ++- advtrains/speed.lua | 57 +++++++++++++++++++++++++++++++++++++++++++++++- advtrains/trainlogic.lua | 6 ++--- 3 files changed, 61 insertions(+), 5 deletions(-) (limited to 'advtrains') 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 -- cgit v1.2.3