Update documentation, purge stale comments

jupyter-client.el

@@ -49,17 +49,20 @@ Clients are removed from this list when their `destructor' is called.")
   "The default timeout in seconds for `jupyter-wait-until'.")
 
 (defvar jupyter-inhibit-handlers nil
-  "Whether or not new requests inhibit some client handlers.
-Do not set this variable directly, locally bind it to either t or
-a list of some of the keywords in `jupyter-message-types' to
-prevent the client from calling some of the handlers. For example
-to prevent a client from calling its execute-reply handler, you
-would do
+  "Whether or not new requests inhibit client handlers.
+If set to t, prevent new requests from running any of the client
+handler methods. If set to a list of `jupyter-message-types',
+prevent handler methods from running only for those message
+types.
+
+For example to prevent a client from calling its :execute-reply
+handler:
 
     (let ((jupyter-inhibit-handlers '(:execute-reply)))
       (jupyter-send-execute-request client ...))
 
-If set to t, disable all client handlers.")
+Do not set this variable directly, let bind it around specific
+requests like the above example.")
 
 ;; Define channel classes for method dispatching based on the channel type
 
@@ -291,11 +294,10 @@ this is called."
 
 ;;; Sending messages
 
-(cl-defmethod jupyter-generate-request ((_client jupyter-kernel-client) _msg)
+(cl-defgeneric jupyter-generate-request ((_client jupyter-kernel-client) _msg)
   "Generate a `jupyter-request' object for MSG.
 This method gives an opportunity for subclasses to initialize a
-`jupyter-request' object or a structure that includes the
-`jupyter-request' slots.
+`jupyter-request' based on the current context.
 
 The default implementation returns a new `jupyter-request' with
 the default value for all slots.

jupyter-org-client.el

@@ -151,9 +151,9 @@ METADATA has the same meaning as in
 
 (defun jupyter-org-image-file-name (data ext)
   "Return a file name based on DATA and EXT.
-`jupyter-org-resource-directory' is used as the directory
-name, the `sha1' hash of DATA is used as the base name, and EXT
-is used as the extension."
+`jupyter-org-resource-directory' is used as the directory name of
+the file, the `sha1' hash of DATA is used as the base name, and
+EXT is used as the extension."
   (let ((dir (prog1 jupyter-org-resource-directory
                (unless (file-directory-p jupyter-org-resource-directory)
                  (make-directory jupyter-org-resource-directory))))
@@ -273,9 +273,12 @@ RENDER-PARAM is the first element of the list returned by
 `jupyter-org-prepare-result', PARAMS are the parameters
 passed to `org-babel-execute:jupyter'.
 
-Append RENDER-PARAM to RESULT-PARAMS if it is a string, otherwise
-if RENDER-PARAM is a cons cell, (KEYWORD . STRING), append
-RENDER-PARAM to the PARAMS."
+Append RENDER-PARAM to the :result-params of PARAMS if it is a
+string. Otherwise, if RENDER-PARAM is a cons cell
+
+    (KEYWORD . STRING)
+
+append RENDER-PARAM to PARAMS."
   (cond
    ((consp render-param)
     (nconc params (list render-param)))

jupyter-repl.el

@@ -71,9 +71,6 @@
 (declare-function markdown-link-at-pos "markdown-mode" (pos))
 (declare-function markdown-follow-link-at-point "markdown-mode")
 
-;; TODO: Read up on how method tags can be used, see
-;; https://ericabrahamsen.net/tech/2016/feb/bbdb-eieio-object-oriented-elisp.html
-
 ;; TODO: Fallbacks for when the language doesn't have a major mode installed.
 
 ;; TODO: Define `jupyter-kernel-manager-after-restart-hook' to update the
@@ -916,7 +913,7 @@ POS defaults to `point'."
           (and (jupyter-channel-alive-p hb)
                (jupyter-hb-beating-p hb))))))
 
-;;; Buffer text manipulation
+;;; Modifying cell code, truncating REPL buffer
 
 (defun jupyter-repl-cell-code ()
   "Return the code of the current cell."
@@ -1449,8 +1446,12 @@ BEG, END, and LEN have the same meaning as in
 
 (defun jupyter-repl-kill-buffer-query-function ()
   "Ask before killing a Jupyter REPL buffer.
-If the REPL buffer is killed, stop the client and possibly the
-kernel that the REPL buffer is connected to."
+If the REPL buffer is killed, stop the client. If the REPL client
+is connected to a kernel with a `jupyter-kernel-manager', kill
+the kernel.
+
+In addition, exit `jupyter-repl-interaction-mode' in all buffers
+associated with the REPL. See `jupyter-repl-associate-buffer'."
   (when (eq major-mode 'jupyter-repl-mode)
     (if (not (jupyter-channels-running-p jupyter-repl-current-client)) t
       (when (y-or-n-p
@@ -1696,7 +1697,6 @@ the `current-buffer' and display the results in a buffer."
   (cl-destructuring-bind (code pos)
       (jupyter-repl-code-context-at-point 'inspect)
     (let ((buf (current-buffer)))
-      ;; TODO: Reset this to nil when the inspect buffer is closed.
       (with-jupyter-repl-doc-buffer "inspect"
         ;; Set this in the inspect buffer so that
         ;; `jupyter-repl-markdown-follow-link-at-point' works in the inspect