Update documentation and commentary

jupyter-channels.el

@@ -23,6 +23,16 @@
 
 ;;; Commentary:
 
+;; Implements synchronous channel types. Each channel is essentially a wrapper
+;; around a `zmq-socket' constrained to a socket type by the type of the
+;; channel and with an associated `zmq-IDENTITY' obtained from the
+;; `jupyter-session' that must be associated with the channel. A heartbeat
+;; channel is distinct from the other channels in that it is implemented using
+;; a timer which periodically pings the kernel depending on how its configured.
+;; In order for communication to occur on the other channels, one of
+;; `jupyter-send' or `jupyter-recv' must be called after starting the channel
+;; with `jupyter-start-channel'.
+
 ;;; Code:
 
 (require 'jupyter-base)

jupyter-client.el

@@ -191,6 +191,8 @@ passed as the argument has a language of LANG."
   (puthash (cadr specializer) specializer jupyter--generic-lang-used)
   (list jupyter--generic-lang-generalizer))
 
+;;; Initializing a `jupyter-kernel-client'
+
 (cl-defmethod initialize-instance ((client jupyter-kernel-client) &rest _slots)
   (cl-call-next-method)
   (push client jupyter--clients)
@@ -385,8 +387,9 @@ If it does not contain a valid value, raise an error."
                             &optional msg-id)
   "Send a message on CLIENT's CHANNEL.
 Return a `jupyter-request' representing the sent message. CHANNEL
-is one of the channel's of CLIENT. TYPE is one of the
-`jupyter-message-types'. MESSAGE is the message sent on CHANNEL.
+is one of the channel keywords, either (:stdin or :shell).
+TYPE is one of the `jupyter-message-types'. MESSAGE is the
+message sent on CHANNEL.
 
 Note that you can manipulate how to handle messages received in
 response to the sent message, see `jupyter-add-callback' and
@@ -1041,7 +1044,7 @@ the user. Otherwise `read-from-minibuffer' is used."
                           implementation_version language_info
                           banner help_links)))))
 
-;;; Evaluation
+;;;; Evaluation
 
 (defun jupyter-eval (code &optional mime)
   "Send an execute request for CODE, wait for the execute result.
@@ -1088,6 +1091,8 @@ nil, return the text/plain representation."
   (declare (indent 1))
   nil)
 
+;;;; Inspection
+
 (cl-defgeneric jupyter-send-inspect-request ((client jupyter-kernel-client)
                                              &key code
                                              (pos 0)
@@ -1108,7 +1113,7 @@ nil, return the text/plain representation."
   (declare (indent 1))
   nil)
 
-;;; Completion contexts
+;;;; Completion
 
 (cl-defgeneric jupyter-code-context (type)
   "Return a list, (CODE POS), for the context around `point'.
@@ -1168,6 +1173,8 @@ in `jupyter-line-context' and is ignored if the region is active."
   (declare (indent 1))
   nil)
 
+;;;; History
+
 (cl-defgeneric jupyter-send-history-request ((client jupyter-kernel-client)
                                              &key
                                              output
@@ -1201,6 +1208,8 @@ in `jupyter-line-context' and is ignored if the region is active."
   (declare (indent 1))
   nil)
 
+;;;; Is Complete
+
 (cl-defgeneric jupyter-send-is-complete-request ((client jupyter-kernel-client)
                                                  &key code)
   "Send an is-complete request."
@@ -1218,6 +1227,8 @@ in `jupyter-line-context' and is ignored if the region is active."
   (declare (indent 1))
   nil)
 
+;;;; Comms
+
 (cl-defgeneric jupyter-send-comm-info-request ((client jupyter-kernel-client)
                                                &key target-name)
   "Send a comm-info request."
@@ -1266,7 +1277,7 @@ in `jupyter-line-context' and is ignored if the region is active."
   (declare (indent 1))
   nil)
 
-;;; Accessing kernel info properties
+;;;; Kernel info
 
 (cl-defmethod jupyter-kernel-info ((client jupyter-kernel-client))
   "Return the kernel info plist of CLIENT.
@@ -1292,8 +1303,6 @@ If the kernel CLIENT is connected to does not respond to a
   "Return the language of the kernel CLIENT is connected to."
   (plist-get (plist-get (jupyter-kernel-info client) :language_info) :name))
 
-;;; Load kernel language support definitions
-
 (defun jupyter-load-language-support (client)
   "Load language support definitions for CLIENT.
 CLIENT is a `jupyter-kernel-client'."
@@ -1320,6 +1329,8 @@ CLIENT is a `jupyter-kernel-client'."
   (declare (indent 1))
   nil)
 
+;;;; Shutdown
+
 (cl-defgeneric jupyter-send-shutdown-request ((client jupyter-kernel-client)
                                               &key restart)
   "Request a shutdown of CLIENT's kernel.

jupyter-messages.el

@@ -246,14 +246,14 @@ Jupyter message, i.e. a list of the form
     (signature header parent-header metadata content buffers...)
 
 If SESSION supports signing messages, then the signature
-resulting from signing of PARTS using SESSION should be equal to
-SIGNATURE. An error is thrown if it is not.
+resulting from the signing of (cdr PARTS) using SESSION should be
+equal to SIGNATURE. An error is thrown if it is not.
 
 The returned plist has elements of the form
 
     (message-part JSON PLIST)
 
-for the keys `:header', `:parent-header', `:metadata',
+for the keys `:header', `:parent-header', `:metadata', and
 `:content'. JSON is the JSON encoded string of the message part.
 For `:header' and `:parent-header', PLIST will be the decoded
 message PLIST for the part. The other message parts are decoded
@@ -315,7 +315,14 @@ message ID will be generated. FLAGS has the same meaning as in
 
 (cl-defmethod jupyter-recv ((session jupyter-session) socket &optional flags)
   "For SESSION, receive a message on SOCKET with FLAGS.
-FLAGS is passed to SOCKET according to `zmq-recv'."
+FLAGS is passed to SOCKET according to `zmq-recv'. Return a cons cell
+
+    (IDENTS . MSG)
+
+where IDENTS are the ZMQ identities associated with MSG and MSG
+is the message property list whose fields can be accessed through
+calls to `jupyter-message-content', `jupyter-message-parent-id',
+and other such functions."
   (let ((msg (zmq-recv-multipart socket flags)))
     (when msg
       (cl-destructuring-bind (idents . parts)