diff options
author | Y. Wang <yw05@forksworld.de> | 2022-10-31 10:57:37 +0100 |
---|---|---|
committer | Y. Wang <yw05@forksworld.de> | 2023-03-23 20:06:02 +0100 |
commit | 7c9fd9179dfcec06107ad1a66346418827bdc4eb (patch) | |
tree | 129f2f9f93cb0b7acc2a5b96e382cac47a55fac6 /advtrains_interlocking/distant.lua | |
parent | 30a0f862488a0cb67f9a8e2aecaf17797ad44a93 (diff) | |
download | advtrains-7c9fd9179dfcec06107ad1a66346418827bdc4eb.tar.gz advtrains-7c9fd9179dfcec06107ad1a66346418827bdc4eb.tar.bz2 advtrains-7c9fd9179dfcec06107ad1a66346418827bdc4eb.zip |
Add API documentation
Diffstat (limited to 'advtrains_interlocking/distant.lua')
-rw-r--r-- | advtrains_interlocking/distant.lua | 47 |
1 files changed, 47 insertions, 0 deletions
diff --git a/advtrains_interlocking/distant.lua b/advtrains_interlocking/distant.lua index f62ca36..22f1c9d 100644 --- a/advtrains_interlocking/distant.lua +++ b/advtrains_interlocking/distant.lua @@ -1,3 +1,8 @@ +--- Distant signaling. +-- This module implements a database backend for distant signal assignments. +-- The actual modifications to signal aspects are still done by signal aspect accessors. +-- @module advtrains.interlocking.distant + local db_distant = {} local db_distant_of = {} @@ -5,6 +10,9 @@ local A = advtrains.interlocking.aspects local pts = advtrains.encode_pos local stp = advtrains.decode_pos +--- Replace the distant signal assignment database. +-- @function load +-- @param db The new database to load. local function db_load(x) if type(x) ~= "table" then return @@ -13,6 +21,9 @@ local function db_load(x) db_distant_of = x.distant_of end +--- Retrieve the current distant signal assignment database. +-- @function save +-- @return The current database. local function db_save() return { distant = db_distant, @@ -22,6 +33,10 @@ end local update_signal, update_main, update_dst +--- Unassign a distant signal. +-- @function unassign_dst +-- @param dst The position of the distant signal. +-- @param[opt=false] force Whether to skip callbacks. local function unassign_dst(dst, force) local pts_dst = pts(dst) local main = db_distant_of[pts_dst] @@ -38,6 +53,10 @@ local function unassign_dst(dst, force) end end +--- Unassign a main signal. +-- @function unassign_main +-- @param main The position of the main signal. +-- @param[opt=false] force Whether to skip callbacks. local function unassign_main(main, force) local pts_main = pts(main) local t = db_distant[pts_main] @@ -57,11 +76,21 @@ local function unassign_main(main, force) db_distant[pts_main] = nil end +--- Remove all (main and distant) signal assignments from a signal. +-- @function unassign_all +-- @param pos The position of the signal. +-- @param[opt=false] force Whether to skip callbacks. local function unassign_all(pos, force) unassign_main(pos) unassign_dst(pos, force) end +--- Assign a distant signal to a main signal. +-- @function assign +-- @param main The position of the main signal. +-- @param dst The position of the distant signal. +-- @param[opt="manual"] by The method of assignment. +-- @param[opt=false] skip_update Whether to skip callbacks. local function assign(main, dst, by, skip_update) local pts_main = pts(main) local pts_dst = pts(dst) @@ -87,11 +116,20 @@ local function pre_occupy(dst, by) db_distant_of[pts_dst] = {nil, by} end +--- Get the distant signals assigned to a main signal. +-- @function get_distant +-- @param main The position of the main signal. +-- @treturn {[pos]=by,...} A table of distant signals, with the positions encoded using `advtrains.encode_pos`. local function get_distant(main) local pts_main = pts(main) return db_distant[pts_main] or {} end +--- Get the main signal assigned the a distant signal. +-- @function get_main +-- @param dst The position of the distant signal. +-- @return The position of the main signal. +-- @return The method of assignment. local function get_main(dst) local pts_dst = pts(dst) local main = db_distant_of[pts_dst] @@ -105,6 +143,9 @@ local function get_main(dst) end end +--- Update all distant signals assigned to a main signal. +-- @function update_main +-- @param main The position of the main signal. update_main = function(main) local pts_main = pts(main) local t = get_distant(main) @@ -114,10 +155,16 @@ update_main = function(main) end end +--- Update the aspect of a distant signal. +-- @function update_dst +-- @param dst The position of the distant signal. update_dst = function(dst) advtrains.interlocking.signal_readjust_aspect(dst) end +--- Update the aspect of a combined (main and distant) signal and all distant signals assigned to it. +-- @function update_signal +-- @param pos The position of the signal. update_signal = function(pos) update_main(pos) update_dst(pos) |