Add code comments in prepare_static_ui_sources.py

examples/gui/data/js/controls.js

@@ -1,4 +1,3 @@
-const UI_INITIAL_GUI = 100;
 const UI_TITEL = 0;
 
 const UI_LABEL = 1;
@@ -113,37 +112,26 @@ function handleVisibilityChange() {
 function start() {
   document.addEventListener("visibilitychange", handleVisibilityChange, false);
   websock = new WebSocket("ws://" + window.location.hostname + "/ws");
-  websock.onopen = function (evt) {
+  websock.onopen = function(evt) {
     console.log("websock open");
     $("#conStatus").addClass("color-green");
     $("#conStatus").text("Connected");
     websockConnected = true;
   };
-
-  websock.onclose = function (evt) {
+  websock.onclose = function(evt) {
     console.log("websock close");
     conStatusError();
   };
-
-  websock.onerror = function (evt) {
+  websock.onerror = function(evt) {
     console.log(evt);
     conStatusError();
   };
-
-  var handleEvent = function (evt) {
-    //console.log(evt);
+  websock.onmessage = function(evt) {
+    console.log(evt);
     var data = JSON.parse(evt.data);
     var e = document.body;
     var center = "";
     switch (data.type) {
-      case UI_INITIAL_GUI:
-        data.controls.forEach(element => {
-          var fauxEvent = {
-            data: JSON.stringify(element)
-          };
-          handleEvent(fauxEvent);
-        });
-        break;
       case UI_TITEL:
         document.title = data.label;
         $("#mainHeader").html(data.label);
@@ -180,13 +168,13 @@ function start() {
             "</button></div>"
         );
         $("#" + data.id).on({
-          touchstart: function (e) {
+          touchstart: function(e) {
             e.preventDefault();
             buttonclick(data.id, true);
           }
         });
         $("#" + data.id).on({
-          touchend: function (e) {
+          touchend: function(e) {
             e.preventDefault();
             buttonclick(data.id, false);
           }
@@ -277,61 +265,61 @@ function start() {
         );
 
         $("#pf" + data.id).on({
-          touchstart: function (e) {
+          touchstart: function(e) {
             e.preventDefault();
             padclick(FOR, data.id, true);
           }
         });
         $("#pf" + data.id).on({
-          touchend: function (e) {
+          touchend: function(e) {
             e.preventDefault();
             padclick(FOR, data.id, false);
           }
         });
         $("#pl" + data.id).on({
-          touchstart: function (e) {
+          touchstart: function(e) {
             e.preventDefault();
             padclick(LEFT, data.id, true);
           }
         });
         $("#pl" + data.id).on({
-          touchend: function (e) {
+          touchend: function(e) {
             e.preventDefault();
             padclick(LEFT, data.id, false);
           }
         });
         $("#pr" + data.id).on({
-          touchstart: function (e) {
+          touchstart: function(e) {
             e.preventDefault();
             padclick(RIGHT, data.id, true);
           }
         });
         $("#pr" + data.id).on({
-          touchend: function (e) {
+          touchend: function(e) {
             e.preventDefault();
             padclick(RIGHT, data.id, false);
           }
         });
         $("#pb" + data.id).on({
-          touchstart: function (e) {
+          touchstart: function(e) {
             e.preventDefault();
             padclick(BACK, data.id, true);
           }
         });
         $("#pb" + data.id).on({
-          touchend: function (e) {
+          touchend: function(e) {
             e.preventDefault();
             padclick(BACK, data.id, false);
           }
         });
         $("#pc" + data.id).on({
-          touchstart: function (e) {
+          touchstart: function(e) {
             e.preventDefault();
             padclick(CENTER, data.id, true);
           }
         });
         $("#pc" + data.id).on({
-          touchend: function (e) {
+          touchend: function(e) {
             e.preventDefault();
             padclick(CENTER, data.id, false);
           }
@@ -430,8 +418,6 @@ function start() {
         break;
     }
   };
-
-  websock.onmessage = handleEvent;
 }
 
 function numberchange(number) {

examples/gui/data/js/controls.min.js

@@ -1,8 +1,8 @@
-const UI_INITIAL_GUI=100;const UI_TITEL=0;const UI_LABEL=1;const UPDATE_LABEL=6;const UI_BUTTON=2;const UI_SWITCHER=3;const UPDATE_SWITCHER=7;const UI_PAD=4;const UI_CPAD=5;const UI_SLIDER=8;const UPDATE_SLIDER=9;const UI_NUMBER=10;const UPDATE_NUMBER=11;const UI_TEXT_INPUT=12;const UPDATE_TEXT_INPUT=13;const UI_GRAPH=14;const CLEAR_GRAPH=15;const ADD_GRAPH_POINT=16;const FOR=0;const BACK=1;const LEFT=2;const RIGHT=3;const CENTER=4;const C_TURQUOISE=0;const C_EMERALD=1;const C_PETERRIVER=2;const C_WETASPHALT=3;const C_SUNFLOWER=4;const C_CARROT=5;const C_ALIZARIN=6;const C_NONE=7;function colorClass(colorId){colorId=Number(colorId);switch(colorId){case C_TURQUOISE:return"turquoise";break;case C_EMERALD:return"emerald";break;case C_PETERRIVER:return"peterriver";break;case C_WETASPHALT:return"wetasphalt";break;case C_SUNFLOWER:return"sunflower";break;case C_CARROT:return"carrot";break;case C_ALIZARIN:return"alizarin";break;case C_NONE:return"";break;default:return"";}}
+const UI_TITEL=0;const UI_LABEL=1;const UPDATE_LABEL=6;const UI_BUTTON=2;const UI_SWITCHER=3;const UPDATE_SWITCHER=7;const UI_PAD=4;const UI_CPAD=5;const UI_SLIDER=8;const UPDATE_SLIDER=9;const UI_NUMBER=10;const UPDATE_NUMBER=11;const UI_TEXT_INPUT=12;const UPDATE_TEXT_INPUT=13;const UI_GRAPH=14;const CLEAR_GRAPH=15;const ADD_GRAPH_POINT=16;const FOR=0;const BACK=1;const LEFT=2;const RIGHT=3;const CENTER=4;const C_TURQUOISE=0;const C_EMERALD=1;const C_PETERRIVER=2;const C_WETASPHALT=3;const C_SUNFLOWER=4;const C_CARROT=5;const C_ALIZARIN=6;const C_NONE=7;function colorClass(colorId){colorId=Number(colorId);switch(colorId){case C_TURQUOISE:return"turquoise";break;case C_EMERALD:return"emerald";break;case C_PETERRIVER:return"peterriver";break;case C_WETASPHALT:return"wetasphalt";break;case C_SUNFLOWER:return"sunflower";break;case C_CARROT:return"carrot";break;case C_ALIZARIN:return"alizarin";break;case C_NONE:return"";break;default:return"";}}
 var websock;var websockConnected=false;function restart(){$(document).add("*").off();$("#row").html("");websock.close();start();}
 function conStatusError(){websockConnected=false;$("#conStatus").removeClass("color-green");$("#conStatus").addClass("color-red");$("#conStatus").html("Error / No Connection ↻");$("#conStatus").off();$("#conStatus").on({click:restart});}
 function handleVisibilityChange(){if(!websockConnected&&!document.hidden){restart();}}
-function start(){document.addEventListener("visibilitychange",handleVisibilityChange,false);websock=new WebSocket("ws://"+window.location.hostname+"/ws");websock.onopen=function(evt){console.log("websock open");$("#conStatus").addClass("color-green");$("#conStatus").text("Connected");websockConnected=true;};websock.onclose=function(evt){console.log("websock close");conStatusError();};websock.onerror=function(evt){console.log(evt);conStatusError();};var handleEvent=function(evt){var data=JSON.parse(evt.data);var e=document.body;var center="";switch(data.type){case UI_INITIAL_GUI:data.controls.forEach(element=>{var fauxEvent={data:JSON.stringify(element)};handleEvent(fauxEvent);});break;case UI_TITEL:document.title=data.label;$("#mainHeader").html(data.label);break;case UI_LABEL:$("#row").append("<div class='two columns card tcenter "+
+function start(){document.addEventListener("visibilitychange",handleVisibilityChange,false);websock=new WebSocket("ws://"+window.location.hostname+"/ws");websock.onopen=function(evt){console.log("websock open");$("#conStatus").addClass("color-green");$("#conStatus").text("Connected");websockConnected=true;};websock.onclose=function(evt){console.log("websock close");conStatusError();};websock.onerror=function(evt){console.log(evt);conStatusError();};websock.onmessage=function(evt){console.log(evt);var data=JSON.parse(evt.data);var e=document.body;var center="";switch(data.type){case UI_TITEL:document.title=data.label;$("#mainHeader").html(data.label);break;case UI_LABEL:$("#row").append("<div class='two columns card tcenter "+
 colorClass(data.color)+
 "'><h5 id='"+
 data.id+
@@ -134,7 +134,7 @@ data.value+
 "' onchange='textchange("+
 data.id+
 ")' />"+
-"</div>");break;case UPDATE_TEXT_INPUT:$("#text"+data.id).val(data.value);break;default:console.error("Unknown type or event");break;}};websock.onmessage=handleEvent;}
+"</div>");break;case UPDATE_TEXT_INPUT:$("#text"+data.id).val(data.value);break;default:console.error("Unknown type or event");break;}};}
 function numberchange(number){var val=$("#num"+number).val();websock.send("nvalue:"+val+":"+number);console.log(val);}
 function textchange(number){var val=$("#text"+number).val();websock.send("tvalue:"+val+":"+number);console.log(val);}
 function buttonclick(number,isdown){if(isdown)websock.send("bdown:"+number);else websock.send("bup:"+number);}

examples/gui/gui.ino

@@ -157,19 +157,11 @@ void setup(void) {
 
   /*
      .begin loads and serves all files from PROGMEM directly.
-     If you want to serve the files from SPIFFS use ESPUI.beginSPIFFS
+     If you want to serve the files from SPIFFS use .beginSPIFFS
      (.prepareFileSystem has to be run in an empty sketch before)
    */
 
   dnsServer.start(DNS_PORT, "*", apIP);
-
-  /*
-   * Optionally you can use HTTP BasicAuth. Keep in mind that this is NOT a
-   SECURE way of limiting access.
-   * Anyone who is able to sniff traffic will be able to intercept your password
-   since it is transmitted in cleartext ESPUI.begin("ESPUI Control", "myuser",
-   "mypassword");
-  */
   ESPUI.begin("ESPUI Control");
 }
 

library.json

@@ -6,13 +6,16 @@
     "type": "git",
     "url": "https://github.com/s00500/ESPUI.git"
   },
-  "authors": [{
+  "authors": [
+    {
       "name": "Lukas Bachschwell",
       "email": "lukas@lbsfilm.at",
       "url": "https://lbsfilm.at",
       "maintainer": true
-  }],
-  "dependencies": [{
+    }
+  ],
+  "dependencies": [
+    {
       "name": "ESP Async WebServer",
       "authors": "Hristo Gochkov",
       "frameworks": "arduino"
@@ -23,7 +26,7 @@
       "frameworks": "arduino"
     }
   ],
-  "version": "1.6.1",
+  "version": "1.6.0",
   "frameworks": "arduino",
   "platforms": "*"
 }

library.properties

@@ -1,5 +1,5 @@
 name=ESPUI
-version=1.6.1
+version=1.6.0
 author=Lukas Bachschwell
 maintainer=Lukas Bachschwell <lukas@lbsfilm.at>
 sentence=ESP32 and ESP8266 Web Interface Library

src/ESPUI.cpp

@@ -492,16 +492,6 @@ void ESPUIClass::updateSlider(int id, int nValue, int clientId) {
   }
 }
 
-void ESPUIClass::updateSlider(String label, int nValue, int clientId) {
-  if (!labelExists(label)) {
-    if (DEBUG_ESPUI)
-      Serial.println("UI ERROR: Element does not " + String(label) +
-                     " exist, cannot update!");
-    return;
-  }
-  updateSlider(getIdByLabel(label), nValue, clientId);
-}
-
 void ESPUIClass::updateSwitcher(int id, bool nValue, int clientId) {
   if (id < cIndex && controls[id]->type == UI_SWITCHER) {
     controls[id]->value = nValue ? 1 : 0;
@@ -613,48 +603,28 @@ bool ESPUIClass::labelExists(String label) {
   return false;
 }
 
-/*
-Convert & Transfer Arduino elements to JSON elements
-Initially this function used to send the control element data individually.
-Due to a change in the ESPAsyncWebserver library this had top be changed to be
-sent as one blob at the beginning. Therefore a new type is used as well
-*/
+// Convert & Transfer Arduino elements to JSON elements
 void ESPUIClass::jsonDom(AsyncWebSocketClient *client) {
-  String json;
-  DynamicJsonBuffer jsonBuffer(2000);
-  JsonObject &root = jsonBuffer.createObject();
-  root["type"] = UI_INITIAL_GUI;
-  JsonArray &items = jsonBuffer.createArray();
-
   for (int i = -1; i < cIndex; i++) {
-    JsonObject &item = jsonBuffer.createObject();
-
+    String json;
+    StaticJsonBuffer<200> jsonBuffer;
+    JsonObject &root = jsonBuffer.createObject();
     if (i == -1) {
-      item["type"] = UI_TITEL;
-      item["label"] = String(ui_title);
+      root["type"] = UI_TITEL;
+      root["label"] = String(ui_title);
     } else {
-      item["type"] = controls[i]->type;
-      item["label"] = String(controls[i]->label);
-      item["value"] = String(controls[i]->value);
-      item["color"] = String(controls[i]->color);
-      item["id"] = String(i);
+      root["type"] = controls[i]->type;
+      root["label"] = String(controls[i]->label);
+      root["value"] = String(controls[i]->value);
+      root["color"] = String(controls[i]->color);
+      root["id"] = String(i);
     }
-    items.add(item);
-  }
-
-  // Send as one big bunch
-  root["controls"] = items;
     root.printTo(json);
     client->text(json);
+  }
 }
 
 void ESPUIClass::beginSPIFFS(const char *_title) {
-  begin(_title, NULL, NULL);
-  basicAuth = false;
-}
-
-void ESPUIClass::beginSPIFFS(const char *_title, const char *username,
-                             const char *password) {
   ui_title = _title;
   server = new AsyncWebServer(80);
   ws = new AsyncWebSocket("/ws");
@@ -676,29 +646,10 @@ void ESPUIClass::beginSPIFFS(const char *_title, const char *username,
 
   ws->onEvent(onWsEvent);
   server->addHandler(ws);
-
-  if (basicAuth && username != NULL && password != NULL) {
-    basicAuthPassword = password;
-    basicAuthUsername = username;
-    basicAuth = true;
-    if (WS_AUTHENTICATION)
-      ws->setAuthentication(this->basicAuthUsername, this->basicAuthPassword);
-    server->serveStatic("/", SPIFFS, "/")
-        .setDefaultFile("index.htm")
-        .setAuthentication(ESPUI.basicAuthUsername, ESPUI.basicAuthPassword);
-
-  } else if (basicAuth) {
-    Serial.println(
-        "Could not enable BasicAuth: Username or password are not set");
-  } else {
   server->serveStatic("/", SPIFFS, "/").setDefaultFile("index.htm");
-  }
 
   // Heap for general Servertest
   server->on("/heap", HTTP_GET, [](AsyncWebServerRequest *request) {
-    if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                  ESPUI.basicAuthPassword))
-      return request->requestAuthentication();
     request->send(200, "text/plain",
                   String(ESP.getFreeHeap()) + " In SPIFFSmode");
   });
@@ -706,50 +657,26 @@ void ESPUIClass::beginSPIFFS(const char *_title, const char *username,
   server->onNotFound(
       [](AsyncWebServerRequest *request) { request->send(404); });
 
+  server->on("/zepto.js", HTTP_GET, [](AsyncWebServerRequest *request) {
+    AsyncWebServerResponse *response = request->beginResponse_P(
+        200, "application/javascript", JS_ZEPTO_GZIP, sizeof(JS_ZEPTO_GZIP));
+    response->addHeader("Content-Encoding", "gzip");
+    request->send(response);
+  });
+
   server->begin();
   if (DEBUG_ESPUI) Serial.println("UI Initialized");
 }
 
 void ESPUIClass::begin(const char *_title) {
-  begin(_title, NULL, NULL);
-  basicAuth = false;
-}
-
-void ESPUIClass::begin(const char *_title, const char *username,
-                       const char *password) {
-  if (basicAuth && username != NULL && password != NULL) {
-    basicAuthPassword = password;
-    basicAuthUsername = username;
-    basicAuth = true;
-  } else if (basicAuth) {
-    Serial.println(
-        "Could not enable BasicAuth: Username or password are not set");
-  }
-
   ui_title = _title;
-
   server = new AsyncWebServer(80);
   ws = new AsyncWebSocket("/ws");
 
   ws->onEvent(onWsEvent);
   server->addHandler(ws);
 
-  if (basicAuth && username != NULL && password != NULL) {
-    basicAuthPassword = password;
-    basicAuthUsername = username;
-    basicAuth = true;
-    if (WS_AUTHENTICATION)
-      ws->setAuthentication(this->basicAuthUsername, this->basicAuthPassword);
-
-  } else if (basicAuth) {
-    Serial.println(
-        "Could not enable BasicAuth: Username or password are not set");
-  }
-
   server->on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
-    if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                  ESPUI.basicAuthPassword))
-      return request->requestAuthentication();
     AsyncWebServerResponse *response =
         request->beginResponse_P(200, "text/html", HTML_INDEX);
     request->send(response);
@@ -758,9 +685,6 @@ void ESPUIClass::begin(const char *_title, const char *username,
   // Javascript files
 
   server->on("/js/zepto.min.js", HTTP_GET, [](AsyncWebServerRequest *request) {
-    if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                  ESPUI.basicAuthPassword))
-      return request->requestAuthentication();
     AsyncWebServerResponse *response = request->beginResponse_P(
         200, "application/javascript", JS_ZEPTO_GZIP, sizeof(JS_ZEPTO_GZIP));
     response->addHeader("Content-Encoding", "gzip");
@@ -768,9 +692,6 @@ void ESPUIClass::begin(const char *_title, const char *username,
   });
 
   server->on("/js/controls.js", HTTP_GET, [](AsyncWebServerRequest *request) {
-    if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                  ESPUI.basicAuthPassword))
-      return request->requestAuthentication();
     AsyncWebServerResponse *response =
         request->beginResponse_P(200, "application/javascript",
                                  JS_CONTROLS_GZIP, sizeof(JS_CONTROLS_GZIP));
@@ -779,9 +700,6 @@ void ESPUIClass::begin(const char *_title, const char *username,
   });
 
   server->on("/js/slider.js", HTTP_GET, [](AsyncWebServerRequest *request) {
-    if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                  ESPUI.basicAuthPassword))
-      return request->requestAuthentication();
     AsyncWebServerResponse *response = request->beginResponse_P(
         200, "application/javascript", JS_SLIDER_GZIP, sizeof(JS_SLIDER_GZIP));
     response->addHeader("Content-Encoding", "gzip");
@@ -791,9 +709,6 @@ void ESPUIClass::begin(const char *_title, const char *username,
   // Stylesheets
 
   server->on("/css/style.css", HTTP_GET, [](AsyncWebServerRequest *request) {
-    if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                  ESPUI.basicAuthPassword))
-      return request->requestAuthentication();
     AsyncWebServerResponse *response = request->beginResponse_P(
         200, "text/css", CSS_STYLE_GZIP, sizeof(CSS_STYLE_GZIP));
     response->addHeader("Content-Encoding", "gzip");
@@ -802,9 +717,6 @@ void ESPUIClass::begin(const char *_title, const char *username,
 
   server->on(
       "/css/normalize.css", HTTP_GET, [](AsyncWebServerRequest *request) {
-        if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                      ESPUI.basicAuthPassword))
-          return request->requestAuthentication();
         AsyncWebServerResponse *response = request->beginResponse_P(
             200, "text/css", CSS_NORMALIZE_GZIP, sizeof(CSS_NORMALIZE_GZIP));
         response->addHeader("Content-Encoding", "gzip");
@@ -813,9 +725,6 @@ void ESPUIClass::begin(const char *_title, const char *username,
 
   // Heap for general Servertest
   server->on("/heap", HTTP_GET, [](AsyncWebServerRequest *request) {
-    if (ESPUI.basicAuth && !request->authenticate(ESPUI.basicAuthUsername,
-                                                  ESPUI.basicAuthPassword))
-      return request->requestAuthentication();
     request->send(200, "text/plain",
                   String(ESP.getFreeHeap()) + " In Memorymode");
   });

src/ESPUI.h

@@ -2,7 +2,6 @@
 #define ESPUI_h
 
 #define DEBUG_ESPUI true
-#define WS_AUTHENTICATION false
 
 #include "Arduino.h"
 #include "ArduinoJson.h"
@@ -41,7 +40,6 @@ typedef struct Control {
 } Control;
 
 // Message Types (and control types)
-#define UI_INITIAL_GUI 100
 #define UI_TITEL 0
 
 #define UI_LABEL 1
@@ -103,11 +101,7 @@ typedef struct Control {
 class ESPUIClass {
  public:
   void begin(const char *_title);        // Setup servers and page in Memorymode
-  void begin(const char *_title, const char *username, const char *password);
-
   void beginSPIFFS(const char *_title);  // Setup servers and page in SPIFFSmode
-  void beginSPIFFS(const char *_title, const char *username,
-                   const char *password);
 
   void prepareFileSystem();  // Initially preps the filesystem and loads a lot
                              // of stuff into SPIFFS
@@ -165,9 +159,6 @@ class ESPUIClass {
   bool labelExists(String label);
 
  private:
-  const char *basicAuthUsername;
-  const char *basicAuthPassword;
-  bool basicAuth = true;
   AsyncWebServer *server;
   AsyncWebSocket *ws;
 };

tools/prepare_static_ui_sources.py

@@ -1,15 +1,42 @@
 #!/usr/bin/env python3
 
-from jsmin import jsmin as jsminify
-from htmlmin import minify as htmlminify
-from csscompressor import compress as cssminify
-import gzip
+### import always available modules
 import sys
 import os.path
 import argparse
 import re
 from glob import glob
 
+### import not always installed modules
+missing = []
+try:
+    from jsmin import jsmin as jsminify
+except ModuleNotFoundError as e:
+    missing.append(e)
+try:
+    from htmlmin import minify as htmlminify
+except ModuleNotFoundError as e:
+    missing.append(e)
+try:
+    from csscompressor import compress as cssminify
+except ModuleNotFoundError as e:
+    missing.append(e)
+try:
+    import gzip
+except ModuleNotFoundError as e:
+    missing.append(e)
+if len(missing) > 0:
+    # ERROR: at least one module is missing
+    for m in missing:
+        print("Cannot find module '%s'." % m.name)
+    print("Can't find %s required python module%s. Please install %s. If you're not sure how, a web search" % (len(missing), "s" if len(missing) > 1 else "", "them" if len(missing) > 1 else "it"))
+    print("for 'python', your operating system/python distribution and 'install modules' should help.")
+    print("For most people on unix-y systems, this line should work (possibly w/o the '3'):\n  pip3 install %s" % " ".join(m.name for m in missing))
+    print("Here's the long documentation: https://packaging.python.org/tutorials/installing-packages/")
+    sys.exit(0)
+
+
+### String template for C header files
 TARGET_TEMPLATE = '''const char {constant}[] PROGMEM = R"=====(
 {minidata}
 )=====";
@@ -17,7 +44,9 @@ TARGET_TEMPLATE = '''const char {constant}[] PROGMEM = R"=====(
 const uint8_t {constant}_GZIP[{gziplen}] PROGMEM = {{ {gzipdata} }};
 '''
 
+
 def parse_arguments(args=None):
+    """ Command line argument parser definitions """
     parser = argparse.ArgumentParser(
         description="Prepares ESPUI header files by minifying and gzipping HTML, JS and CSS source files.")
     parser.add_argument("--auto", "--all", "-a", dest="auto", action="store_true",
@@ -36,6 +65,20 @@ def parse_arguments(args=None):
     return args
 
 def get_context(infile, outfile):
+    """ This function creates a 'context object': a dictionary containing all the data needed. 
+    Dictionary members:
+        infile:		Full path to the input file or directory as given or autodetected
+        indir:		Full path to the infile parent.
+        dir:		Full path to the input directory tree (indir or parent of indir).
+        name:		Filename of infile excluding extension (i.e. filename up until the first dot)
+        type:		Lowercase extension of infile; one of: html, js, css.
+        outfile:	Full path to the output file or directory as given or autodetected.
+        outdir:		Full path to output directory.
+        outfilename:	Filename of outfile.
+        minifile:	Full path and filename of the intermediary minified file.
+        constant:	C header file constant name derived from infile.
+    If infile == minifile, the input file already is minified (contains ".min.")
+    """
     infile	= os.path.realpath(infile)
     dir, name, type 	= (os.path.basename(os.path.dirname(infile)), os.path.basename(infile).split(os.path.extsep)[0], os.path.basename(infile).split(os.path.extsep)[-1] )
     type = type.strip(".").lower()
@@ -58,6 +101,11 @@ def get_context(infile, outfile):
     return locals()
     
 def perform_gzip(c):
+    """ Performs GZIP on c['minidata'].
+    The returned context object will contain additional fields:
+        gzipdata:	Comma-separated string of decimal byte values representing gzipped data.
+        gziplen:	Count of decimal byte values in gzipdata.
+    """
     compressed = gzip.compress(bytes(c['minidata'], 'utf-8'))
     c['gzipdata'] = ','.join([ str(b) for b in compressed ])
     c['gziplen'] = len(compressed)
@@ -65,6 +113,9 @@ def perform_gzip(c):
     return c
     
 def perform_minify(c):
+    """ Performs minification on c['infile'].
+    The returned context object contains the additional field minidata: A string of minified file contents.
+    """
     with open(c['infile']) as infile:
         minifier = {
             'css': cssminify, 
@@ -73,19 +124,27 @@ def perform_minify(c):
         }.get(c['type']) or htmlminify
         print("  Using %s minifier" % c['type'])
         c['minidata'] = minifier(infile.read())
-    return perform_gzip(c)
+    return c
 
 def process_file(infile, outdir, storemini=True):
+    """ Processes one file """
     print("Processing file %s" % infile)
+    # Evaluate file and target context
     c = get_context(infile, outdir)
+    # Minify file data
     c = perform_minify(c)
+    # Gzip minified data
+    c = perform_gzip(c)
+    
     if storemini:
+        # Write intermediary minified file
         if c['infile'] == c['minifile']:
             print("  Original file is already minified, refusing to overwrite it")
         else:
             print("  Writing minified file %s" % c['minifile'])
             with open(c['minifile'], 'w+') as minifile:
                 minifile.write(c['minidata'])
+    # Write minified and gzipped data to C header file
     with open(c['outfile'], 'w+') as outfile:
         print("  Using C constant names %s and %s_GZIP" % (c['constant'], c['constant']))
         print("  Writing C header file %s" % c['outfile'])
@@ -95,6 +154,10 @@ def filenamefilter(pattern, strings):
     return filter(re.compile(pattern).search, strings)        
         
 def process_dir(sourcedir, outdir, recursive=True, storemini=True):
+    """ Processes a directory tree, recursively. Calls process_file on each HTML/CSS/JS file found.
+    Skips intermediary minified files. Standalone minified files (i.e. files containing ".min." that
+    do not have a full version) are processed without minifying again.
+    """
     pattern = r'/*\.(css|js|htm|html)$'
     files = glob(sourcedir + "/**/*", recursive=True)+glob(sourcedir + "/*") if recursive else glob(sourcedir + "/*")
     files = filenamefilter(pattern, files)
@@ -105,6 +168,7 @@ def process_dir(sourcedir, outdir, recursive=True, storemini=True):
             process_file(f, outdir, storemini)
             
 def check_args(args):
+    """ Checks argumental sanity and exits if the arguments are insane. """
     abort = 0
     if not os.path.exists(args.sources):
         print("ERROR: Source %s does not exist" % args.sources)
@@ -120,8 +184,12 @@ def check_args(args):
         sys.exit(abort)
 
 def main(args):
+    """ main entry point. """
+    # default source if not given: realpath(../examples/gui/data)
     args.sources = os.path.realpath(args.sources or os.sep.join((os.path.dirname(os.path.realpath(__file__)), "..", "examples", "gui", "data")))
+    # default target if not given: realpath(../src)
     args.target  = os.path.realpath(args.target  or os.sep.join((os.path.dirname(os.path.realpath(__file__)), "..", "src")))
+    # check arguments
     check_args(args)
     if os.path.isfile(args.sources):
         print("Source %s is a file, will process one file only." % args.sources)