add some more comments

src/pages/blockly/blockly_protocol.ts

@@ -10,7 +10,16 @@ import { LoggingProvider } from '../../providers/logging/logging';
 export class BlocklyMessageProtocol {
   ready: Promise<void>
 
+  // defines the expected response type for each request type
+  private reqResPatterns: BlocklyReqPatterns = {
+    'getSketch': 'sketch',
+    'getXml': 'xml',
+    'setXml': null,
+    'toggleView': null,
+  }
+
   constructor (private blocklyFrame: ElementRef, private log: LoggingProvider) {
+    // set up event listeners for non-request log messages
     window.addEventListener('message', (ev: IframePostMessageEvent) => {
       if (ev.data.type === 'log')
         this.log.warn('log entry from blockly:', ev.data)
@@ -18,6 +27,7 @@ export class BlocklyMessageProtocol {
         this.log.debug(`received ${ev.data.type} message from blockly`, { message: ev.data })
     })
 
+    // resolve ready promise once the blocklyFrame is ready
     this.ready = new Promise(resolve => {
       window.addEventListener('message', (ev: IframePostMessageEvent) => {
         // @HACK @FIXME: timeout is required, as blockly resolves some async functions
@@ -27,13 +37,6 @@ export class BlocklyMessageProtocol {
     })
   }
 
-  private reqResPatterns: BlocklyReqPatterns = {
-    'getSketch': 'sketch',
-    'getXml': 'xml',
-    'setXml': null,
-    'toggleView': null,
-  }
-
   toggleView() { this.sendRequest({ type: 'toggleView' }) }
   setXml(data: string) { this.sendRequest({ type: 'setXml', data }) }
 

src/providers/logging/logging.ts

@@ -38,6 +38,8 @@ export class LoggingProvider {
     }
   }
 
+  // construct a new logger with a new component name and default fields,
+  // inheriting existing default fields
   createChild (component: string, defaultFields: object = {}) {
     const child = new LoggingProvider(this.http, this.plt, this.storage, this.translate)
     Object.assign(child.defaultFields, defaultFields, { component })
@@ -72,6 +74,7 @@ export class LoggingProvider {
     const logentry = { } as LogMessage
     let msg = ''
 
+    // fields can be strings, which are appended to the message; or objects, which are merged.
     for (const param of fields) {
       if (typeof param === 'object')
         Object.assign(logentry, param)
@@ -82,6 +85,7 @@ export class LoggingProvider {
     if (msg)
       logentry.msg = msg
 
+    // add the static and dynamic default fields
     Object.assign(logentry, this.defaultFields, {
       time: new Date().toISOString(),
       levelText: LogLevel[level],