Add API documentation

1 files changed, 0 insertions, 165 deletions

diff --git a/advtrains_interlocking/signal_api.lua b/advtrains_interlocking/signal_api.lua
index e615692..54202f0 100644
--- a/advtrains_interlocking/signal_api.lua
+++ b/advtrains_interlocking/signal_api.lua
@@ -1,170 +1,5 @@
 -- Signal API implementation
 
-
---[[
-Signal aspect table:
-Note: All speeds are measured in m/s, aka the number of + signs in the HUD.
-asp = {
-	main = <int speed>,
-		-- Main signal aspect, tells state and permitted speed of next section
-		-- 0 = section is blocked
-		-- >0 = section is free, speed limit is this value
-		-- -1 = section is free, maximum speed permitted
-		-- false/nil = Signal doesn't provide main signal information, retain current speed limit.
-	shunt = <boolean>,
-		-- Whether train may proceed as shunt move, on sight
-		-- main aspect takes precedence over this
-		-- When main==0, train switches to shunt move and is restricted to speed 6
-	proceed_as_main = <boolean>,
-		-- If an approaching train is a shunt move and 'shunt' is false,
-		-- the train may proceed as a train move under the "main" aspect
-		-- if the main aspect permits it (i.e. main!=0)
-		-- If this is not set, shunt moves are NOT allowed to switch to
-		-- a train move, and must stop even if "main" would permit passing.
-		-- This is intended to be used for "Halt for shunt moves" signs.
-	
-	dst = <int speed>,
-		-- Distant signal aspect, tells state and permitted speed of the section after next section
-		-- The character of these information is purely informational
-		-- At this time, this field is not actively used
-		-- 0 = section is blocked
-		-- >0 = section is free, speed limit is this value
-		-- -1 = section is free, maximum speed permitted
-		-- false/nil = Signal doesn't provide distant signal information.
-	
-	-- the character of call_on and dead_end is purely informative
-	call_on = <boolean>, -- Call-on route, expect train in track ahead (not implemented yet)
-	dead_end = <boolean>, -- Route ends on a dead end (e.g. bumper) (not implemented yet)
-
-	w_speed = <integer>,
-	-- "Warning speed restriction". Supposed for short-term speed
-	-- restrictions which always override any other restrictions
-	-- imposed by "speed" fields, until lifted by a value of -1
-	-- (Example: german Langsamfahrstellen-Signale)
-	}
-}
-
-== How signals actually work in here ==
-Each signal (in the advtrains universe) is some node that has at least the
-following things:
-- An "influence point" that is set somewhere on a rail
-- An aspect which trains that pass the "influence point" have to obey
-
-There can be static and dynamic signals. Static signals are, roughly
-spoken, signs, while dynamic signals are "real" signals which can display
-different things.
-
-The node definition of a signal node should contain those fields:
-groups = {
-  	advtrains_signal = 2,
-	save_in_at_nodedb = 1,
-}
-advtrains = {
-	set_aspect = function(pos, node, asp)
-		-- This function gets called whenever the signal should display
-		-- a new or changed signal aspect. It is not required that
-		-- the signal actually displays the exact same aspect, since
-		-- some signals can not do this by design. However, it must
-		-- display an aspect that is at least as restrictive as the passed
-		-- aspect as far as it is capable of doing so.
-		-- Examples:
-		-- - pure shunt signals can not display a "main" aspect
-		--   and have no effect on train moves, so they will only ever
-		--   honor the shunt.free field for their aspect.
-		-- - the german Hl system can only signal speeds of 40, 60
-		--   and 100 km/h, a speed of 80km/h should then be signalled
-		--   as 60 km/h instead.
-		-- In turn, it is not guaranteed that the aspect will fulfill the
-		-- criteria put down in supported_aspects.
-		-- If set_aspect is present, supported_aspects should also be declared.
-		
-		-- The aspect passed in here can always be queried using the
-		-- advtrains.interlocking.signal_get_supposed_aspect(pos) function.
-		-- It is always DANGER when the signal is not used as route signal.
-		
-		-- For static signals, this function should be completely omitted
-		-- If this function is omitted, it won't be possible to use
-		-- route setting on this signal.
-	end,
-	supported_aspects = {
-		-- A table which tells which different types of aspects this signal
-		--  is able to display. It is used to construct the "aspect editing"
-		--  formspec for route programming (and others) It should always be
-		--  present alongside with set_aspect. If this is not specified but
-		--  set_aspect is, the user will be allowed to select any aspect.
-		-- Any of the fields marked with <boolean/nil> support 3 types of values:
-				nil: if this signal can switch between free/blocked
-				false: always shows "blocked", unchangable
-				true: always shows "free", unchangable
-		-- Any of the "speed" fields should contain a list of possible values
-		--  to be set as restriction. If omitted, the value of the described
-		--  field is always assumed to be false (no information)
-		-- A speed of 0 means that the signal can show a "blocked" aspect
-		--  (which is probably the case for most signals)
-		-- If the signal can signal "no information" on one of the fields
-		--  (thus false is an acceptable value), include false in the list
-		-- If your signal can only display a single speed (may it be -1),
-		--  always enclose that single value into a list. (such as {-1})
-		main = {<speed1>, ..., <speedn>} or nil,
-		dst = {<speed1>, ..., <speedn>} or nil,
-		shunt = <boolean/nil>,
-		
-		call_on = <boolean/nil>,
-		dead_end = <boolean/nil>,
-		w_speed = {<speed1>, ..., <speedn>} or nil,
-		
-	},
-	Example for supported_aspects:
-	supported_aspects = {
-		main = {0, 6, -1}, -- can show either "Section blocked", "Proceed at speed 6" or "Proceed at maximum speed"
-		dst = {0, false}, -- can show only if next signal shows "blocked", no other information.
-		shunt = false, -- shunting by this signal is never allowed.
-		
-		call_on = false,
-		dead_end = false,
-		w_speed = nil,
-		-- none of the information can be shown by the signal
-		
-	},
-	
-	get_aspect = function(pos, node)
-		-- This function gets called by the train safety system. It
-		should return the aspect that this signal actually displays,
-		not preferably the input of set_aspect.
-		-- For regular, full-featured light signals, they will probably
-		honor all entries in the original aspect, however, e.g.
-		simple shunt signals always return main=false regardless of
-		the set_aspect input because they can not signal "Halt" to
-		train moves.
-		-- advtrains.interlocking.DANGER contains a default "all-danger" aspect.
-		-- If your signal does not cover certain sub-tables of the aspect,
-		the following reasonable defaults are automatically assumed:
-		main = false (unchanged)
-		dst = false (unchanged)
-		shunt = false (shunting not allowed)
-		info = {} (no further information)
-	end,
-}
-on_rightclick = advtrains.interlocking.signal_rc_handler
-can_dig =  advtrains.interlocking.signal_can_dig
-after_dig_node = advtrains.interlocking.signal_after_dig
-
-(If you need to specify custom can_dig or after_dig_node callbacks,
-please call those functions anyway!)
-
-Important note: If your signal should support external ways to set its
-aspect (e.g. via mesecons), there are some things that need to be considered:
-- advtrains.interlocking.signal_get_supposed_aspect(pos) won't respect this
-- Whenever you change the signal aspect, and that aspect change
-did not happen through a call to
-advtrains.interlocking.signal_set_aspect(pos, asp), you are
-*required* to call this function:
-advtrains.interlocking.signal_on_aspect_changed(pos)
-in order to notify trains about the aspect change.
-This function will query get_aspect to retrieve the new aspect.
-
-]]--
-
 local DANGER = {
 	main = 0,
 	shunt = false,