core: add comments

core.lua

@@ -302,9 +302,11 @@ F.core.train_enter = function(place, dir, train)
 		assert(false, msg)
 	end
 
+	-- for report to consoles
 	local flags = {"train_enter"}
 	local payload = {["place"] = place, ["dir"] = dir, ["train"] = train}
 
+	-- check if train is coming in via interfaces
 	local is_entry = false
 	if S.caches.interfaces == nil then
 		F.core.generate_interfaces_cache()
@@ -314,6 +316,7 @@ F.core.train_enter = function(place, dir, train)
 			is_entry = true
 			table.insert(flags, "real_entry")
 	end
+
 	if is_entry then
 		if S.trains[train.id] ~= nil then
 			atc_send("BB")
@@ -322,6 +325,7 @@ F.core.train_enter = function(place, dir, train)
 			F.util.debug(msg)
 			assert(false, msg)
 		end
+		-- register the train
 		S.trains[train.id] = train
 		F.util.debug("Train "..F.util.dump(train.id).." entered via "..F.util.dump(place).."→"..F.util.dump(dir))
 	else
@@ -333,6 +337,7 @@ F.core.train_enter = function(place, dir, train)
 			assert(false, msg)
 		end
 	end
+
 	-- update attributes
 	for k,v in pairs(train) do
 		S.trains[train.id][k] = v
@@ -349,6 +354,7 @@ F.core.train_enter = function(place, dir, train)
 
 	if train.desired == nil or
 		(train.desired.state == "routed" and train.desired.place == place and train.desired.dir == dir) then
+			-- if we have completed a route (or have just started)
 			local dest = F.core.train_find_next_destination(train)
 			if dest == nil then
 				if is_entry then
@@ -367,6 +373,7 @@ F.core.train_enter = function(place, dir, train)
 					print(msg)
 				end
 			else
+				-- schedule a routing task
 				train.desired = {
 					["state"] = "routed",
 					["place"] = dest.place.fullname,
@@ -376,6 +383,7 @@ F.core.train_enter = function(place, dir, train)
 				payload.new_task = "route"
 			end
 	elseif (train.desired.state == "routed" or train.desired.state == "parked") and (train.desired.place ~= place or train.desired.dir ~= dir) then
+		-- if we are not finished routing or finding the parking space, schedule another routing task
 		F.core.validate_place_dir_combo(train.desired.place, train.desired.dir)
 		table.insert(S.tasks, {["type"] = "route", ["train"] = train, ["dest"] = {
 			["place"] = S.places[train.desired.place],
@@ -404,6 +412,7 @@ F.core.train_exit = function(place, dir, train)
 		assert(false, msg)
 	end
 
+	-- for report to consoles
 	local flags = {"train_exit"}
 	local payload = {["place"] = place, ["dir"] = dir, ["train"] = train}
 
@@ -414,6 +423,7 @@ F.core.train_exit = function(place, dir, train)
 		F.util.debug(msg)
 		assert(false, msg)
 	end
+
 	-- use the original object
 	train = S.trains[train.id]
 	-- save current place and dir
@@ -432,6 +442,7 @@ end
 
 
 F.core.reject_train = function(train)
+	-- a train came in which we don't know what to do with, send it back through the interface it came in
 	local msg = "Unexpected train! Train entered "..F.util.dump(train.place.name).."→"..F.util.dump(train.dir).."! Sending back..."
 	if S.generated_places == nil or S.generated_places.interfaces == nil then
 		-- save and announce error
@@ -440,9 +451,11 @@ F.core.reject_train = function(train)
 		F.util.debug(msg)
 		assert(false, msg)
 	end
+
 	if S.caches.interfaces == nil then
 		F.core.generate_interfaces_cache()
 	end
+	-- find the exit interface, if there is any
 	if S.caches.interfaces[train.place.fullname] ~= nil and S.caches.interfaces[train.place.fullname][train.dir] ~= nil then
 		local interface = S.caches.interfaces[train.place.fullname][train.dir].interface
 		if interface.exit ~= nil then
@@ -462,6 +475,7 @@ F.core.reject_train = function(train)
 end
 
 F.core.expect_train = function(train, dest)
+	-- verify that the train appeared where we expected it
 	if dest == nil then
 		dest = train.expected
 	end