Update documentation and comments

Author: nnicandro

jupyter-client.el

@@ -139,17 +139,16 @@ buffer.")
 
 (defun jupyter-initialize-connection (client &optional file-or-plist)
   "Initialize CLIENT with a connection FILE-OR-PLIST.
-When FILE-OR-PLIST is a file name, read the JSON connection
-information from the file and initialize CLIENT's connection and
-channels from the file's contents. When FILE-OR-PLIST is a plist,
-initialize CLIENT's connection and channels from the plist. When
-FILE-OR-PLIST is nil, then the `conn-info' slot of CLIENT is used
-to initialize the connection. The necessary keys to initialize a
-connection can be found at
+If FILE-OR-PLIST is the name of a file, assume the file to be a
+kernel connection file and initialize CLIENT from its contents.
+If FILE-OR-PLIST is a property list, initialize CLIENT using its
+properties. If FILE-OR-PLIST is nil, initialize CLIENT's
+connection using CLIENT's `conn-info' slot. The necessary keys
+and values to initialize a connection can be found at
 http://jupyter-client.readthedocs.io/en/latest/kernels.html#connection-files.
 
 As a side effect, if CLIENT is already connected to a kernel its
-connection is terminated before initializing."
+connection is terminated before initializing a new one."
   (cl-check-type client jupyter-kernel-client)
   (let ((conn-info (if file-or-plist
                        (oset client conn-info

jupyter-kernel-manager.el

@@ -107,7 +107,7 @@ SLOTS are the slots used to initialize the client with.")
 CLASS should be a subclass of `jupyter-kernel-client', a new
 instance of CLASS initialized with SLOTS and configured to
 connect to MANAGER's kernel. The returned `jupyter-kernel-client'
-will have MANAGER set as its parent-instance slot, see
+will have MANAGER set as its `parent-instance' slot, see
 `jupyter-connection'."
   (unless (child-of-class-p class 'jupyter-kernel-client)
     (signal 'wrong-type-argument (list '(subclass jupyter-kernel-client) class)))
@@ -242,7 +242,10 @@ kernel. Starting a kernel involves the following steps:
             (oset manager conn-file (expand-file-name
                                      (format "kernel-%d.json" (process-id proc))
                                      jupyter-runtime-directory))
-            (rename-file conn-file (oref manager conn-file))
+            ;; Gaurd against a kernel that dies after starting. For example,
+            ;; the Julia kernel JuliaLang/IJulia.jl/issues/596 on Julia 0.6.0
+            (when (process-live-p proc)
+              (rename-file conn-file (oref manager conn-file)))
             (jupyter-start-channels manager)
             (progress-reporter-done reporter)
             manager))))))
@@ -334,19 +337,19 @@ subprocess."
   "Start a managed Jupyter kernel.
 KERNEL-NAME is the name of the kernel to start. It can also be
 the prefix of a valid kernel name, in which case the first kernel
-in `jupyter-available-kernelspecs' that has a kernel name with
-KERNEL-NAME as prefix will be used. Optional argument
-CLIENT-CLASS should be a subclass of `jupyer-kernel-client' which
-will be used to initialize a new client connected to the new
-kernel. CLIENT-CLASS defaults to `jupyter-kernel-client'.
+in `jupyter-available-kernelspecs' that has KERNEL-NAME as a
+prefix will be used. Optional argument CLIENT-CLASS is a subclass
+of `jupyer-kernel-client' and will be used to initialize a new
+client connected to the kernel. CLIENT-CLASS defaults to
+`jupyter-kernel-client'.
 
 Return a cons cell (KM . KC) where KM is the
 `jupyter-kernel-manager' that manages the lifetime of the kernel
-subprocess. KC is a new client connected to the kernel and whose
+subprocess. KC is a new client connected to the kernel whose
 class is CLIENT-CLASS. The client is connected to the kernel with
 all channels listening for messages and the heartbeat channel
-un-paused. Note that the client's parent-instance slot will also
-be set to the kernel manager instance, see
+un-paused. Note that the client's `parent-instance' slot will
+also be set to the kernel manager instance, see
 `jupyter-make-client'."
   (setq client-class (or client-class 'jupyter-kernel-client))
   (unless (child-of-class-p client-class 'jupyter-kernel-client)

jupyter-repl-client.el

@@ -77,7 +77,9 @@
   :group 'jupyter-repl)
 
 (defcustom jupyter-repl-maximum-is-complete-timeout 2
-  "Maximum number of seconds to wait for a is-complete reply."
+  "Maximum number of seconds to wait for an is-complete reply.
+When no is-complete reply is received from the kernel within this
+timeout, the built-in is-complete handler is used."
   :group 'jupyter-repl)
 
 (defcustom jupyter-repl-history-maximum-length 100
@@ -1194,7 +1196,7 @@ kernel that the REPL buffer is connected to."
   (not (and (eq major-mode 'jupyter-repl-mode)
             ;; TODO: Handle case when multiple clients are connected, i.e. do
             ;; we want to also delete a kernel if this is the last client
-            ;; connected. See eieio instance tracker.
+            ;; connected. See `eieio-instance-tracker'.
             (or (and (jupyter-repl-client-has-manager-p)
                      (jupyter-kernel-alive-p
                       (oref jupyter-repl-current-client parent-instance)))
@@ -1381,9 +1383,9 @@ CODE and POS are the code to send and the position within the
 code, respectively.
 
 If BUFFER is non-nil then it should be the buffer in which to
-insert the inspection text returned from kernel. After the
-inspection text is inserted into BUFFER, BUFFER is returned. If
-BUFFER is nil, then return the inspection text. In both cases the
+insert the inspection text returned from the kernel. After the
+inserting the text into BUFFER, BUFFER is returned. If BUFFER is
+nil, just return the inspection text. In both cases the
 inspection text is already in a form suitable for display.
 
 TIMEOUT is how long to wait (in seconds) for the kernel to

ob-jupyter.el

@@ -65,16 +65,13 @@ See `org-babel-jupyter-file-name'."
 
 (defun org-babel-variable-assignments:jupyter (params &optional lang)
   "Assign variables in PARAMS according to the Jupyter kernel language.
-Use `org-babel-jupyter-src-block-lang' to get the kernel language
-of the src-block ELEMENT and call the variable assignment
-function for the language. ELEMENT defaults to the
-`org-element-at-point'. So if LANG is the kernel language, then
-call
+LANG is the kernel language of the source block. If LANG is nil,
+get the kernel language from the current source block.
 
-    org-babel-variable-assignments:LANG
-
-If the above function doesn't exist or if no kernel langauge can
-be found, fall back to `org-babel-variable-assignments:python'."
+The variables are assigned by looking for the function
+`org-babel-variable-assignments:LANG'. If this function does not
+exist or if LANG cannot be determined, assign variables using
+`org-babel-variable-assignments:python'."
   (let* ((lang (or lang
                    (save-excursion
                      (when (re-search-backward
@@ -91,18 +88,16 @@ be found, fall back to `org-babel-variable-assignments:python'."
 BODY is the code to expand, PARAMS should be the header arguments
 of the src block with BODY as its code, and VAR-LINES should be
 the list of strings containing the variables to evaluate before
-executing body.
+executing body. LANG is the kernel language of the source block.
 
 This function is similar to
-`org-babel-variable-assignments:jupyter' in that it finds the
-kernel language of the src-block ELEMENT, defaulting to the
-`org-element-at-point', to find get the kernel language of BODY.
-So if LANG is the kernel language, call the function
-
-    org-babel-expand-body:LANG
+`org-babel-variable-assignments:jupyter' in that it attempts to
+find the kernel language of the source block if LANG is not
+provided.
 
-to expand BODY. If the above function doesn't exist or if no
-kernel langauge can be found fall back to
+BODY is expanded by calling the function
+`org-babel-expand-body:LANG'. If this function doesn't exist or
+if LANG cannot be determined, fall back to
 `org-babel-expand-body:generic'."
   (let* ((lang (or lang
                    (save-excursion
@@ -132,7 +127,8 @@ the header variables in PARAMS."
       (when var-lines
         (jupyter-repl-replace-cell-code
          (mapconcat #'identity var-lines "\n"))
-        ;; For `org-babel-load-session:jupyter'
+        ;; For `org-babel-load-session:jupyter', ensure that the loaded code
+        ;; starts on a new line.
         (when no-execute
           (insert "\n")))
       (unless no-execute
@@ -353,7 +349,7 @@ removal."
 For example, call `org-babel-python-table-or-string' on the
 results when rendering scalar data for a python code block.
 
-RENDER-RESULT should be the cons cell returned by
+RENDER-RESULT is the cons cell returned by
 `org-babel-jupyter-prepare-result' and KERNEL-LANG is the kernel
 language."
   (cl-destructuring-bind (render-param . result) render-result
@@ -364,23 +360,26 @@ language."
 
 (defun org-babel-jupyter-insert-results (results params kernel-lang)
   "Insert RESULTS at the current source block location.
-RESULTS is either a a single pair or a list of pairs with the form
+RESULTS is either a single pair or a list of pairs, each pair
+having the form
 
     (RENDER-PARAM . RESULT)
 
 i.e. the pairs returned by `org-babel-jupyter-prepare-result'.
-PARAMS should be the parameters passed to
-`org-babel-execute:jupyter'. KERNEL-LANG is the language of the
-kernel for the current source block. If optional argument APPEND
-is non-nil, then append RESULTS to the current results. The
-results will also be appended, regardless of the value of APPEND,
-if RESULTS is a list."
+PARAMS are the parameters passed to `org-babel-execute:jupyter'.
+KERNEL-LANG is the language of the kernel that produced RESULTS.
+
+Note that for a list of results, the result which will appear
+will be the last one in the list unless the source block has an
+\"append\" or \"prepend\" parameter or some other way that
+prevents `org-babel-insert-result' from clearing a result when
+inserting a new one."
   ;; Unless this is a list of results
   (unless (car-safe (car results))
     (setq results (list results)))
   (cl-loop
-   ;; FIXME: This is a hack that relies on `org-babel-insert-result' only caring
-   ;; about the parameters of the info and not anything else.
+   ;; FIXME: This is a hack that relies on `org-babel-insert-result' only
+   ;; caring about the parameters of the info and not anything else.
    with info = (list nil nil params)
    with result-params = (alist-get :result-params params)
    for (render-param . result) in
@@ -439,6 +438,7 @@ PARAMS."
                       (org-babel-jupyter--inject-render-param "append" params))
                     (org-babel-jupyter-insert-results result params kernel-lang))
                 (push result results)))))
+      ;; TODO: Handle stream output and errors similar to ob-ipython
       (jupyter-add-callback req
         :stream
         (lambda (msg)
@@ -494,10 +494,9 @@ PARAMS."
 
 (defun org-babel-jupyter-make-language-alias (kernel lang)
   "Simimilar to `org-babel-make-language-alias' but for Jupyter src-blocks.
-KERNEL should be the name of a the default kernel using for the
-kernel LANG. All necessary org-babel functions for a language
-with the name jupyter-LANG will be aliased to the jupyter
-functions."
+KERNEL should be the name of the default kernel to use for kernel
+LANG. All necessary org-babel functions for a language with the
+name jupyter-LANG will be aliased to the jupyter functions."
   (dolist (fn '("execute" "expand-body" "prep-session" "edit-prep"
                 "variable-assignments" "load-session"))
     (let ((sym (intern-soft (concat "org-babel-" fn ":jupyter"))))
@@ -523,8 +522,7 @@ Optional argument REFRESH has the same meaning as in
   (cl-loop
    for (kernel . (_dir . spec)) in (jupyter-available-kernelspecs refresh)
    for lang = (plist-get spec :language)
-   ;; Only make aliases the first time a new language appears
-   unless (functionp (intern (concat "org-babel-execute:jupyter-" lang)))
+   unless (member lang languages) collect lang into languages and
    do (org-babel-jupyter-make-language-alias kernel lang)
    ;; (add-to-list 'org-babel-tangle-lang-exts
    ;;              (cons (concat "jupyter-" lang) file_extension))