aboutsummaryrefslogtreecommitdiff
path: root/advtrains_interlocking/signal_aspects.lua
diff options
context:
space:
mode:
authorY. Wang <yw05@forksworld.de>2022-10-31 10:57:37 +0100
committerY. Wang <yw05@forksworld.de>2023-03-23 20:06:02 +0100
commit7c9fd9179dfcec06107ad1a66346418827bdc4eb (patch)
tree129f2f9f93cb0b7acc2a5b96e382cac47a55fac6 /advtrains_interlocking/signal_aspects.lua
parent30a0f862488a0cb67f9a8e2aecaf17797ad44a93 (diff)
downloadadvtrains-7c9fd9179dfcec06107ad1a66346418827bdc4eb.tar.gz
advtrains-7c9fd9179dfcec06107ad1a66346418827bdc4eb.tar.bz2
advtrains-7c9fd9179dfcec06107ad1a66346418827bdc4eb.zip
Add API documentation
Diffstat (limited to 'advtrains_interlocking/signal_aspects.lua')
-rw-r--r--advtrains_interlocking/signal_aspects.lua49
1 files changed, 40 insertions, 9 deletions
diff --git a/advtrains_interlocking/signal_aspects.lua b/advtrains_interlocking/signal_aspects.lua
index c381fd2..37af7aa 100644
--- a/advtrains_interlocking/signal_aspects.lua
+++ b/advtrains_interlocking/signal_aspects.lua
@@ -1,5 +1,11 @@
+--- Signal aspect handling.
+-- @module advtrains.interlocking.aspects
+
local type2defs = {}
+--- Register a type 2 signal group.
+-- @function register_type2
+-- @param def The definition table.
local function register_type2(def)
local t = {type = 2}
local name = def.name
@@ -42,19 +48,21 @@ local function register_type2(def)
type2defs[name] = t
end
+--- Get the definition of a type 2 signal group.
+-- @function get_type2_definition
+-- @param name The name of the signal group.
+-- @return[1] The definition for the signal group (if present).
+-- @return[2] The nil constant (otherwise).
local function get_type2_definition(name)
return type2defs[name]
end
-local function get_type2_danger(group)
- local def = type2defs[group]
- if not def then
- return nil
- end
- local main = def.main
- return main[#main]
-end
-
+--- Get the name of the distant aspect before the current aspect.
+-- @function get_type2_dst
+-- @param group The name of the group.
+-- @param name The name of the current aspect.
+-- @return[1] The name of the distant aspect (if present).
+-- @return[2] The nil constant (otherwise).
local function get_type2_dst(group, name)
local def = type2defs[group]
if not def then
@@ -67,6 +75,12 @@ local function get_type2_dst(group, name)
return def.main[math.max(1, aspidx-1)].name
end
+--- Convert a type 2 signal aspect to a type 1 signal aspect.
+-- @function type2_to_type1
+-- @param suppasp The table of supported aspects for the signal.
+-- @param asp The name of the signal aspect.
+-- @return[1] The type 1 signal aspect table (if present).
+-- @return[2] The nil constant (otherwise).
local function type2_to_type1(suppasp, asp)
local name = suppasp.group
local shift = suppasp.dst_shift
@@ -111,6 +125,13 @@ local function type2_to_type1(suppasp, asp)
return t
end
+--- Convert a type 1 signal aspect table to a type 2 signal aspect.
+-- @function type1_to_type2main
+-- @param asp The type 1 signal aspect table
+-- @param group The signal aspect group
+-- @param[opt=0] shift The shift for the signal aspect.
+-- @return[1] The name of the signal aspect (if present).
+-- @return[2] The nil constant (otherwise).
local function type1_to_type2main(asp, group, shift)
local def = type2defs[group]
if not def then
@@ -130,6 +151,11 @@ local function type1_to_type2main(asp, group, shift)
return t_main[math.max(1, idx-(shift or 0))].name
end
+--- Compare two signal aspect tables.
+-- @function equalp
+-- @param asp1 The first signal aspect table.
+-- @param asp2 The second signal aspect table.
+-- @return Whether the two signal aspect tables give the same (type 1 aspect) information.
local function equalp(asp1, asp2)
if asp1 == asp2 then -- same reference
return true
@@ -146,6 +172,11 @@ local function equalp(asp1, asp2)
return true
end
+--- Compare two signal aspect tables.
+-- @function not_equalp
+-- @param asp1 The first signal aspect table.
+-- @param asp2 The second signal aspect table.
+-- @return The negation of `equalp``(asp1, asp2)`.
local function not_equalp(asp1, asp2)
return not equalp(asp1, asp2)
end