From d3329b74a5604196f7c4c0baa026cef1928afa78 Mon Sep 17 00:00:00 2001
From: janisozaur <janisozaur@users.noreply.github.com>
Date: Mon, 16 Nov 2015 13:59:01 +0100
Subject: [PATCH] Comment expected cmdline_call_action results

---
 src/cmdline.c | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/cmdline.c b/src/cmdline.c
index 0b0eb4b232..58b233db03 100644
--- a/src/cmdline.c
+++ b/src/cmdline.c
@@ -120,13 +120,19 @@ int cmdline_run(const char **argv, int argc)
 #endif // DISABLE_NETWORK
 
 	if (argc != 0) {
+		// see comment next to cmdline_call_action for expected return codes
 		gExitCode = cmdline_call_action(argv, argc);
 		if (gExitCode < 0) {
+			// action failed, don't change exit code
+			// and don't start the game
 			return 0;
 		} else if (gExitCode > 0) {
+			// action successful, but don't start the game
+			// change exit code to success
 			gExitCode = 0;
 			return 0;
 		}
+		// start the game, so far exit code means success.
 	}
 
 	// Headless mode requires a park to open
@@ -202,6 +208,7 @@ static int cmdline_for_none(const char **argv, int argc)
 	}
 }
 
+// see comment next to cmdline_call_action for expected return codes
 struct { const char *firstArg; cmdline_action action; } cmdline_table[] = {
 	{ "intro", cmdline_for_intro },
 	{ "edit", cmdline_for_edit },
@@ -215,6 +222,19 @@ struct { const char *firstArg; cmdline_action action; } cmdline_table[] = {
 #endif
 };
 
+/**
+ * This function delegates starting the game to different handlers, if found.
+ * 
+ * Three cases of return values are supported:
+ * - result < 0 means failure, will exit with error code
+ *   This case is useful when user provided wrong arguments or the requested
+ *   action failed
+ * - result > 0 means success, won't start game, will exit program with success code
+ *   This case is useful when you want to do some batch action and signalize
+ *   success to the user.
+ * - result == 0 means success, will launch the game.
+ *   This is default when ran with no arguments.
+ */
 static int cmdline_call_action(const char **argv, int argc)
 {
 	for (int i = 0; i < countof(cmdline_table); i++) {