Add notes on how EmacsJupyter works

js/emacs-jupyter.js

@@ -1,8 +1,42 @@
+// NOTE: Info on widgets http://ipywidgets.readthedocs.io/en/latest/examples/Widget%20Low%20Level.html
 var disposable = require('@phosphor/disposable');
 var coreutils = require('@jupyterlab/coreutils');
+// The KernelFutureHandler allows comms to register their callbacks to be
+// called when messages are received in response to a request sent to the
+// kernel.
 var KernelFutureHandler = require('@jupyterlab/services/kernel/future').KernelFutureHandler;
+// The CommHandler object handles comm interaction to/from the kernel. It takes
+// a target_name, usually jupyter.widget, and a comm_id. It takes care of
+// sending comm messages to the kernel and calls the callback methods of a Comm
+// when a comm_msg is received from the kernel.
+//
+// A Comm object is essentially a wrapper around a CommHandler that updates the
+// CommHandler callbacks and registers callbacks on the futures created when a
+// Comm sends a message on the shell channel.
 var CommHandler = require('@jupyterlab/services/kernel/comm').CommHandler;
 
+
+// A CommManager takes care of registering new comm targets and creating new
+// comms and holding a list of all the live comms.
+
+// It looks like I just ned to implement the IKernel interface and pass the
+// object that implements it to CommManager, this way I can create new comms
+// with CommManager.new_comm when handling comm_open messages. In the IKernel
+// interface, I'll just redirect all the message sending functions to Emacs.
+
+// It looks like widgets send messages through the callbacks of a
+// KernelFutureHandler so I will have to redirect all received messages that
+// originated from a request generated by skewer.postJSON back to the
+// JavaScript environment. Emacs then acts as an intermediary, capturing kernel
+// messages and re-packaging them to send to the Javascript environment.
+//
+// It looks like whenever the kernel receives a message it accesse the correct
+// future object using this.futures.get and calls handleMsg function of the
+// future.
+//
+// The flow of message with respect to Comm objects is that Comm object send
+// shell messages, then widgets register callbacks on the future.
+
 var EmacsJupyter = function(options, port) {
     var _this = this;
 
@@ -10,11 +44,25 @@ var EmacsJupyter = function(options, port) {
     // This is the Jupyter session id
     this.clientId = options.clientId;
     this.isDisposed = false;
+    // A mapping from comm_id's to promises that resolve to their open Comm
+    // objects.
     this.commPromises = new Map();
+    // The targetRegistry is a dictionary mapping target names to target
+    // functions that are called whenever a new Comm is requested to be open by
+    // the kernel. The target function gets called with the initial comm_open
+    // message data and a comm handler for the new Comm.
     this.targetRegistry = {};
+    // A mapping of msg_id's for messages sent to the kernel and their
+    // KernelFutureHandler objects.
     this.futures = new Map();
+    // The WidgetManager that connects comms to their corresponding widget
+    // models, construct widget views, load widget modules, and get the current
+    // widget state.
     this.widgetManager = null;
     this.widgetState = null;
+    // The CommManager that registers the target names and their target
+    // functions handles opening and closing comms for a particular
+    // target name.
     this.commManager = null;
     this.messagePromise = new Promise(function (resolve) { resolve(); });
 
@@ -210,18 +258,6 @@ EmacsJupyter.prototype._unregisterComm = function (commId) {
     this.commPromises.delete(commId);
 };
 
-// It looks like widgets send messages through the callbacks of a
-// KernelFutureHandler so I will have to redirect all received messages that
-// originated from a request generated by skewer.postJSON back to the
-// JavaScript environment. Emacs then acts as an intermediary, capturing kernel
-// messages and re-packaging them to send to the Javascript environment.
-//
-// It looks like whenever the kernel receives a message it accesse the correct
-// future object using this.futures.get and calls handleMsg function of the
-// future.
-//
-// The flow of message with respect to Comm objects is that Comm object send
-// shell messages, then widgets register callbacks on the future.
 EmacsJupyter.prototype.sendShellMessage = function(msg, expectReply, disposeOnDone) {
     var _this = this;
     if (expectReply === void 0) { expectReply = false; }
@@ -304,23 +340,3 @@ EmacsJupyter.prototype.handleMessage = function(msg) {
         });
     }
 }
-
-// The CommHandler object handles comm interaction to/from the kernel. It takes
-// a target_name, usually jupyter.widget, and a comm id and takes care of
-// sending comm messages to the kernel and calls the callback methods when a
-// comm msg is received from the kernel.
-
-// A Comm object is just a wrapper around a CommHandler that updates its
-// callbacks
-
-// The targetRegistry is a dictionary mapping target names to target functions
-// to call whenever a new Comm is requested to be open by the kernel. The
-// target function gets called with the message data cand a comm handler.
-
-// A CommManager takes care of registering new comm targets and creating new
-// comms and holding a list of all the live comms.
-
-// It looks like I just ned to implement the IKernel interface and pass the
-// object that implements it to CommManager, this way I can create new comms
-// with CommManager.new_comm when handling comm_open messages. In the IKernel
-// interface, I'll just redirect all the message sending functions to Emacs.