Fix checkdoc warnings

jupyter-base.el

@@ -362,7 +362,7 @@ To access all the objects in TRACKING-SYMBOL, use
 
 (defun jupyter-all-objects (sym)
   "Return all tracked objects in tracking SYM.
-SYMB is a symbol used for tracking objects that inherit from
+SYM is a symbol used for tracking objects that inherit from the class
 `jupyter-instance-tracker'."
   (let ((table (symbol-value sym)))
     (when (hash-table-p table)

jupyter-channel-ioloop.el

@@ -49,7 +49,7 @@
 
 ;; Meant to be used in the subprocess
 (defvar jupyter-ioloop-channels nil
-  "List of `jupyter-sync-channel's in an ioloop controlling Jupyter channels.")
+  "A list of synchronous channels in an ioloop controlling Jupyter channels.")
 
 (defvar jupyter-ioloop-session nil
   "The `jupyter-session' used when initializing Jupyter channels.")

jupyter-channels.el

@@ -45,12 +45,11 @@
 
 (defvar jupyter-hb-consider-dead-periods 5
   "Number of `time-to-dead' periods until the `kernel-died-cb' is called.
-A `jupyter-hb-channel' sends a ping to the kernel on the
-heartbeat channel and waits until `time-to-dead' seconds to see
-if the kernel sent a ping back. If the kernel does not send a
-ping back for
+A ping is sent to the kernel on a heartbeat channel and waits
+until `time-to-dead' seconds to see if the kernel sent a ping
+back. If the kernel doesn't send a ping back after
 
-    (* `time-to-dead'`jupyter-hb-consider-dead-periods')
+    (* `time-to-dead' `jupyter-hb-consider-dead-periods')
 
 seconds, consider the kernel dead and call the callback in the
 `kernel-died-cb' slot of a `jupyter-hb-channel'. See

jupyter-client.el

@@ -43,7 +43,9 @@
 ;; the `org-mode' client whenever `point' is inside a code
 ;; block.
 (defvar jupyter-current-client nil
-  "The `jupyter-kernel-client' for the `current-buffer'.")
+  "The kernel client for the `current-buffer'.
+This is also let bound whenever a message is handled by a
+kernel.")
 
 (put 'jupyter-current-client 'permanent-local t)
 (make-variable-buffer-local 'jupyter-current-client)
@@ -185,7 +187,7 @@ passed as the argument has a language of LANG."
   (jupyter-all-objects 'jupyter--clients))
 
 (defun jupyter-find-client-for-session (session-id)
-  "Return the `jupyter-kernel-client' for SESSION-ID."
+  "Return the kernel client whose session has SESSION-ID."
   (or (cl-find-if
        (lambda (x) (string= (jupyter-session-id (oref x session)) session-id))
        (jupyter-clients))
@@ -616,7 +618,7 @@ when MSG-TYPE is received for REQ."
 (defun jupyter-add-callback (req msg-type cb &rest callbacks)
   "Add a callback to run when a message is received for a request.
 REQ is a `jupyter-request' returned by one of the request methods
-of a `jupyter-kernel-client'. MSG-TYPE is one of the keys in
+of a kernel client. MSG-TYPE is one of the keys in
 `jupyter-message-types'. CB is the callback function to run when
 a message with MSG-TYPE is received for REQ.
 
@@ -1184,7 +1186,7 @@ If the kernel CLIENT is connected to does not respond to a
 
 (defun jupyter-load-language-support (client)
   "Load language support definitions for CLIENT.
-CLIENT is a `jupyter-kernel-client'."
+CLIENT is a kernel client."
   (cl-assert (object-of-class-p client 'jupyter-kernel-client))
   (let* ((lang (jupyter-kernel-language client))
          (support (intern (concat "jupyter-" lang))))

jupyter-ioloop.el

@@ -257,12 +257,11 @@ anything.
 
 Some arguments are treated specially:
 
-If one of ARGS is a list (<sym> jupyter-channel) where <sym> is
-any symbol, then the parent process that sends EVENT to IOLOOP is
-expected to give a channel type as the argument and the type will
-be converted into the corresponding channel object and bound to
-<sym> before evaluating BODY. The available channels are in
-`jupyter-ioloop-channels'."
+If one of ARGS is a list (<sym> tag) where <sym> is any symbol,
+then the parent process that sends EVENT to IOLOOP is expected to
+send a value that will be bound to <sym> and be handled by an
+argument handler associated with tag before BODY is evaluated in
+the IOLOOP process, see `jupyter-ioloop-add-arg-type'."
   (declare (indent 3) (doc-string 4) (debug t))
   (unless (stringp doc)
     (when doc

jupyter-kernel-manager.el

@@ -93,7 +93,7 @@ default kernel is a python kernel."
     (lambda () (jupyter-kernel-manager--cleanup manager t))))
 
 (defun jupyter-kernel-managers ()
-  "Return a list of all `jupyter-kernel-manager's."
+  "Return a list of all live kernel managers."
   (jupyter-all-objects 'jupyter--managers))
 
 (cl-defgeneric jupyter-make-client ((manager jupyter-kernel-manager) class &rest slots)
@@ -122,8 +122,8 @@ connect to MANAGER's kernel."
 
 (defun jupyter--start-kernel (kernel-name env args)
   "Start a kernel.
-For a `jupyter-kernel-manager', MANAGER, state a kernel named
-KERNEL-NAME with ENV and ARGS.
+Start a kernel named KERNEL-NAME with ENV and ARGS. Return the
+newly created kernel process.
 
 If ENV is non-nil, then it should be a plist containing
 environment variable names as keywords along with their
@@ -133,9 +133,7 @@ environment before starting the kernel.
 ARGS should be a list of command line arguments used to start the
 kernel process. The name of the command used to start the kernel
 should be the first element of ARGS and the rest of the elements
-of ARGS are the arguments of the command.
-
-Return the newly created kernel process."
+of ARGS are the arguments of the command."
   (let* ((process-environment
           (append
            ;; The first entry takes precedence when duplicated variables

jupyter-repl.el

@@ -190,8 +190,8 @@ executing BODY."
 
 (defmacro jupyter-repl-append-output (client req &rest body)
   "Switch to CLIENT's buffer, move to the end of REQ, and run BODY.
-REQ is a `jupyter-request' previously made using CLIENT, a
-`jupyter-repl-client'.
+REQ is a `jupyter-request' previously made using CLIENT, a REPL
+client.
 
 `point' is moved to the `jupyter-repl-cell-beginning-position' of
 the cell *after* REQ, this position is where any newly generated
@@ -618,7 +618,7 @@ POS defaults to `point'."
       (/= (jupyter-repl-cell-end-position) (point-max))))
 
 (defun jupyter-repl-client-has-manager-p ()
-  "Does the `jupyter-current-client' have a `jupyter-kernel-manager'?"
+  "Return non-nil if the `jupyter-current-client' has a kernel manager."
   (and jupyter-current-client
        (oref jupyter-current-client manager)))
 
@@ -1152,8 +1152,7 @@ Note, the overriding method should call `cl-call-next-method'."
 (defun jupyter-repl-kill-buffer-query-function ()
   "Ask before killing a Jupyter REPL buffer.
 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.
+is connected to a kernel with a kernel manager, kill the kernel.
 
 In addition, exit `jupyter-repl-interaction-mode' in all buffers
 associated with the REPL. See `jupyter-repl-associate-buffer'."
@@ -1745,8 +1744,8 @@ synchronize the execution state, and insert a new input prompt."
 
 (defun jupyter-repl-interrupt-kernel ()
   "Interrupt the kernel if possible.
-A kernel can be interrupted if it was started using a
-`jupyter-kernel-manager'. See `jupyter-start-new-kernel'."
+A kernel can be interrupted if it was started using a kernel
+manager. See `jupyter-start-new-kernel'."
   (interactive)
   (if (not (jupyter-repl-client-has-manager-p))
       (user-error "Cannot interrupt non-subprocess kernels")
@@ -2279,8 +2278,8 @@ purposes and SYNTAX-TABLE is the syntax table of MODE."
 
 (defun jupyter-repl--new-repl (client &optional repl-name)
   "Initialize a new REPL buffer based on CLIENT.
-CLIENT is a `jupyter-repl-client' already connected to its kernel
-and has a non-nil kernel-info slot.
+CLIENT is a REPL client already connected to its kernel and has a
+non-nil kernel-info slot.
 
 A new REPL buffer communicating with CLIENT's kernel is created
 and set as CLIENT's buffer slot. If CLIENT already has a non-nil