From 0fafeaf8d2019fa88d81e212f5a69d475c5572cb Mon Sep 17 00:00:00 2001
From: Ferry Boender <ferry.boender@gmail.com>
Date: Mon, 18 May 2015 08:24:38 +0200
Subject: [PATCH] Document how scriptform.py works.

---
 src/scriptform.py | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/scriptform.py b/src/scriptform.py
index c982c11..965745f 100755
--- a/src/scriptform.py
+++ b/src/scriptform.py
@@ -1,6 +1,33 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+# Scriptform roughly works like this:
+#
+# 1. Instantiate a ScriptForm class. This takes care of loading the form config
+#    (json) file and provides methods to run the server.
+# 2. If running as a daemon:
+#    a) Instantiate the Daemon class
+#    b) Hook up a callback to shutdown the ScriptForm server
+#    c) Start the daemon. This detaches from the console.
+# 3. Start the ScriptForm server. This listens on a port for incoming HTTP
+#    connections.
+# 4. If a request comes in, it is dispatched to the ScriptFormWebApp request
+#    handler.ScriptFormWebApp inherits from the WebAppHandler class. The
+#    WebAppHandler determines which method of ScriptFormWebApp the request
+#    should be dispatched to.
+# 5. Depending on the request, a method is called on ScriptFormWebApp. These
+#    methods render HTML to as a response.
+# 6. If a form is submitted, its fields are validated and the script callback
+#    is called. Depending on the output type, the output of the script is either
+#    captured and displayed as HTML to the user or directly streamed to the
+#    browser.
+# 7. GOTO 4.
+# 8. Upon receiving an OS signal (kill, etc) the daemon calls the shutdown
+#    callback.
+# 9. The shutdown callback starts a new thread (otherwise the webserver blocks
+#    until the next request) to stop the server.
+# 10. The program exits.
+
 # Todo:
 #
 #  - How does script_raw check the exitcode? Document this.