From 1b3b16c355a3387bfbac9560a144253481e62684 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Ritzl?= <bjorn.ritzl@gmail.com>
Date: Fri, 1 Dec 2017 09:31:50 +0100
Subject: [PATCH] Added more documentation. Changed monarch.get_stack()

---
 .../{main.collection => example.collection}   |  2 +-
 monarch/monarch.lua                           | 34 +++++++++++++++++--
 test/test_monarch.lua                         |  2 +-
 3 files changed, 34 insertions(+), 4 deletions(-)
 rename example/{main.collection => example.collection} (99%)

diff --git a/example/main.collection b/example/example.collection
similarity index 99%
rename from example/main.collection
rename to example/example.collection
index d57e0fb..fce48dd 100644
--- a/example/main.collection
+++ b/example/example.collection
@@ -1,4 +1,4 @@
-name: "main"
+name: "example"
 scale_along_z: 0
 embedded_instances {
   id: "menu"
diff --git a/monarch/monarch.lua b/monarch/monarch.lua
index f8c1a20..9ee4e2f 100644
--- a/monarch/monarch.lua
+++ b/monarch/monarch.lua
@@ -43,6 +43,10 @@ local function screen_from_script()
 	end
 end
 
+
+--- Check if a screen exists in the current screen stack
+-- @param id
+-- @return true of the screen is in the stack
 function M.in_stack(id)
 	for i = 1, #stack do
 		if stack[i].id == id then
@@ -52,13 +56,33 @@ function M.in_stack(id)
 	return false
 end
 
+
+--- Check if a screen is at the top of the stack
+-- (primarily used for unit tests, but could have a usecase outside tests)
+-- @param id
+-- @return true if the screen is at the top of the stack
 function M.is_top(id)
 	local top = stack[#stack]
 	return top and top.id == id or false
 end
 
+
+--- Register a new screen
+-- This is done automatically by the screen.script. It is expected that the
+-- caller of this function is a script component attached to the same game
+-- object as the proxy. This is required since monarch will acquire and
+-- release input focus of the game object where the proxy is attached.
+-- @param id Unique id of the screen
+-- @param proxy URL to the collection proxy containing the screen
+-- @param popup true the screen is a popup
+-- @param transition_url Optional URL to a script that is
+-- responsible for the screen transitions
+-- @param focus_url Optional URL to a script that is to be notified of
+-- focus lost/gained events
 function M.register(id, proxy, popup, transition_url, focus_url)
 	assert(not screens[id], ("There is already a screen registered with id %s"):format(tostring(id)))
+	assert(proxy, "You must provide a collection proxy URL")
+	local url = msg.url(proxy)
 	screens[id] = {
 		id = id,
 		proxy = proxy,
@@ -69,6 +93,9 @@ function M.register(id, proxy, popup, transition_url, focus_url)
 	}
 end
 
+--- Unregister a screen
+-- This is done automatically by the screen.script
+-- @param id Id of the screen to unregister
 function M.unregister(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 	screens[id] = nil
@@ -279,11 +306,14 @@ function M.on_message(message_id, message, sender)
 	end
 end
 
-
+--- Get a list of ids for the current screen stack
+-- (primarily used for unit testing, but could have uses outside testing)
+-- @return Table with screen ids. First entry is at the bottom of the
+-- stack and the last value is at the top (and currently visible)
 function M.get_stack()
 	local s = {}
 	for k,v in pairs(stack) do
-		s[k] = v
+		s[k] = v.id
 	end
 	return s
 end
diff --git a/test/test_monarch.lua b/test/test_monarch.lua
index 706e24f..ac9f450 100644
--- a/test/test_monarch.lua
+++ b/test/test_monarch.lua
@@ -39,7 +39,7 @@ return function()
 			error("Stack length mismatch", 2)
 		end
 		for i=1,#actual_screens do
-			if actual_screens[i].id ~= expected_screens[i] then
+			if actual_screens[i] ~= expected_screens[i] then
 				error("Stack content not matching", 2)
 			end
 		end