Fix all checkdoc issues.

1 files changed, 206 insertions, 76 deletions

diff --git a/nrepl.el b/nrepl.el
index 57087aeb..48bcfce2 100644
--- a/nrepl.el
+++ b/nrepl.el
@@ -136,7 +136,7 @@
   :group 'nrepl)
 
 (defmacro nrepl-propertize-region (props &rest body)
-  "Execute BODY and add PROPS to all the text it inserts.
+  "Add PROPS to all text inserted by executing BODY.
 More precisely, PROPS are added to the region between the point's
 positions before and after executing BODY."
   (let ((start (make-symbol "start-pos")))
@@ -244,6 +244,7 @@ change the setting's value."
  'nrepl-sync-response)
 
 (defun nrepl-reset-markers ()
+  "Reset all repl markers."
   (dolist (markname '(nrepl-output-start
                       nrepl-output-end
                       nrepl-prompt-start-mark
@@ -299,7 +300,7 @@ change the setting's value."
       (nreverse result))))
 
 (defun nrepl-netstring (string)
-  "Encode string in bencode."
+  "Encode STRING in bencode."
   (let ((size (string-bytes string)))
     (format "%s:%s" size string)))
 
@@ -308,7 +309,9 @@ change the setting's value."
   (concat "d" (apply 'concat (mapcar 'nrepl-netstring message)) "e"))
 
 (defun nrepl-eval-region (start end)
-  "Evaluate region."
+  "Evaluate the region.
+The two arguments START and END are character positions;
+they can be in either order."
   (interactive "r")
   (nrepl-interactive-eval (buffer-substring-no-properties start end)))
 
@@ -332,7 +335,8 @@ change the setting's value."
         (list (point) end)))))
 
 (defun nrepl-eval-expression-at-point (&optional prefix)
-  "Evaluate the current toplevel form."
+  "Evaluate the current toplevel form, and print result in the mini-buffer.
+With a PREFIX argument, print the result in the current buffer."
   (interactive "P")
   (let ((form (nrepl-expression-at-point)))
     (if prefix
@@ -419,6 +423,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
     (forward-line (1- line))))
 
 (defun nrepl-jump-to-def-handler (buffer)
+  "Create a handler for jump-to-def in BUFFER."
   ;; TODO: got to be a simpler way to do this
   (nrepl-make-response-handler buffer
                                (lambda (buffer value)
@@ -473,6 +478,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                        (nrepl-current-tooling-session))))
 
 (defun nrepl-jump (query)
+  "Jump to the definition of QUERY."
   (interactive "P")
   (nrepl-read-symbol-name "Symbol: " 'nrepl-jump-to-def query))
 
@@ -502,11 +508,15 @@ Removes any leading slash if on Windows.  Uses `find-file'."
       (car strlst))))
 
 (defun nrepl-dispatch-complete-symbol (str)
+  "Return a list of completions for STR.
+Dispatch to the nREPL \"complete\" op if supported,
+otherwise dispatch to internal completion function."
   (if (nrepl-op-supported-p "complete")
       (nrepl-completion-complete-op-fn str)
     (nrepl-completion-complete-core-fn str)))
 
 (defun nrepl-complete-at-point ()
+  "Complete the symbol at point."
   (let ((sap (symbol-at-point)))
     (when (and sap (not (in-string-p)))
       (let ((bounds (bounds-of-thing-at-point 'symbol)))
@@ -514,9 +524,12 @@ Removes any leading slash if on Windows.  Uses `find-file'."
               (completion-table-dynamic #'nrepl-dispatch-complete-symbol))))))
 
 (defun nrepl-eldoc-format-thing (thing)
+  "Format the eldoc THING."
   (propertize thing 'face 'font-lock-function-name-face))
 
 (defun nrepl-highlight-args (arglist pos)
+  "Format the the function ARGLIST for eldoc.
+POS is the index of the currently highlighted argument."
   (let* ((rest-pos (position '& arglist))
          (i 0))
     (mapconcat
@@ -534,14 +547,21 @@ Removes any leading slash if on Windows.  Uses `find-file'."
              (setq i (1+ i)))))) arglist " ")))
 
 (defun nrepl-highlight-arglist (arglist pos)
+  "Format the ARGLIST for eldoc.
+POS is the index of the argument to highlight."
   (concat "[" (nrepl-highlight-args arglist pos) "]"))
 
 (defun nrepl-eldoc-format-arglist (arglist pos)
+  "Format all the ARGLIST for eldoc.
+POS is the index of current argument."
   (concat "("
           (mapconcat (lambda (args) (nrepl-highlight-arglist args pos))
                      (read arglist) " ") ")"))
 
 (defun nrepl-eldoc-handler (buffer the-thing the-pos)
+  "Create a response handler for nrepl eldoc in BUFFER.
+This will produce an eldoc message for THE-THING
+highlighing all arguments matching THE-POS."
   (lexical-let ((thing the-thing)
                 (pos the-pos))
     (nrepl-make-response-handler
@@ -554,6 +574,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
      nil nil nil)))
 
 (defun nrepl-eldoc-info-in-current-sexp ()
+  "Return a list of the current sexp and the current argument index."
   (save-excursion
     (let ((argument-index (1- (eldoc-beginning-of-sexp))))
       ;; If we are at the beginning of function name, this will be -1.
@@ -582,6 +603,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                          (nrepl-current-tooling-session)))))
 
 (defun nrepl-turn-on-eldoc-mode ()
+  "Turn on eldoc mode in the current buffer."
   (make-local-variable 'eldoc-documentation-function)
   (setq eldoc-documentation-function 'nrepl-eldoc)
   (apply 'eldoc-add-command nrepl-extra-eldoc-commands)
@@ -593,6 +615,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
   "List of paths to directories with Javadoc.")
 
 (defun nrepl-javadoc-op (symbol-name)
+  "Invoke the nREPL \"javadoc\" op on SYMBOL-NAME."
   (nrepl-send-op
    "javadoc"
    `("symbol" ,symbol-name "ns" ,nrepl-buffer-ns
@@ -606,6 +629,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
     nil nil nil)))
 
 (defun nrepl-javadoc-handler (symbol-name)
+  "Invoke the nREPL \"javadoc\" op on SYMBOL-NAME if available."
   (when symbol-name
     (let ((bounds (bounds-of-thing-at-point 'symbol)))
       (if (nrepl-op-supported-p "javadoc")
@@ -613,13 +637,14 @@ Removes any leading slash if on Windows.  Uses `find-file'."
         (message "No Javadoc middleware available")))))
 
 (defun nrepl-javadoc (query)
-  "Browse Javadoc on the Java class at point."
+  "Browse Javadoc on the Java class QUERY at point."
   (interactive "P")
   (nrepl-read-symbol-name "Javadoc for: " 'nrepl-javadoc-handler query))
 
 ;;; Response handlers
 (defmacro nrepl-dbind-response (response keys &rest body)
-  "Destructure an nREPL response dict."
+  "Destructure an nREPL RESPONSE dict.
+Bind the value of the provided KEYS and execute BODY."
   `(let ,(loop for key in keys
                collect `(,key (cdr (assoc ,(format "%s" key) ,response))))
      ,@body))
@@ -627,6 +652,9 @@ Removes any leading slash if on Windows.  Uses `find-file'."
 (put 'nrepl-dbind-response 'lisp-indent-function 2)
 
 (defun nrepl-make-response-handler (buffer value-handler stdout-handler stderr-handler done-handler)
+  "Make a response handler for BUFFER.
+Uses the specified VALUE-HANDLER, STDOUT-HANDLER, STDERR-HANDLER and
+DONE-HANDLER as appropriate."
   (lexical-let ((buffer buffer)
                 (value-handler value-handler)
                 (stdout-handler stdout-handler)
@@ -662,6 +690,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                               (funcall done-handler buffer))))))))))
 
 (defun nrepl-stdin-handler (buffer)
+  "Make a stdin response handler for BUFFER."
   (nrepl-make-response-handler buffer
                                (lambda (buffer value)
                                  (nrepl-emit-result buffer value t))
@@ -672,6 +701,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                                nil))
 
 (defun nrepl-handler (buffer)
+  "Make a nrepl evaluation handler for BUFFER."
   (nrepl-make-response-handler buffer
                                (lambda (buffer value)
                                  (nrepl-emit-result buffer value t))
@@ -683,6 +713,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                                  (nrepl-emit-prompt buffer))))
 
 (defun nrepl-interactive-eval-handler (buffer)
+  "Make an interactive eval handler for BUFFER."
   (nrepl-make-response-handler buffer
                                (lambda (buffer value)
                                  (message "%s" value))
@@ -693,6 +724,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                                '()))
 
 (defun nrepl-load-file-handler (buffer)
+  "Make a load file handler for BUFFER."
   (let (current-ns (nrepl-current-ns))
     (nrepl-make-response-handler buffer
                                  (lambda (buffer value)
@@ -706,6 +738,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                                  '())))
 
 (defun nrepl-interactive-eval-print-handler (buffer)
+  "Make a handler for evaluating and printing result in BUFFER."
   (nrepl-make-response-handler buffer
                                (lambda (buffer value)
                                  (with-current-buffer buffer
@@ -716,6 +749,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                                '()))
 
 (defun nrepl-popup-eval-print-handler (buffer)
+  "Make a handler for evaluating and printing result in popup BUFFER."
   (nrepl-make-response-handler buffer
                                (lambda (buffer str)
                                  (nrepl-emit-into-popup-buffer buffer str))
@@ -725,6 +759,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                                '()))
 
 (defun nrepl-popup-eval-out-handler (buffer)
+  "Make a handler for evaluating and printing stdout/stderr in popup BUFFER."
   (nrepl-make-response-handler buffer
                                '()
                                (lambda (buffer str)
@@ -734,6 +769,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
                                '()))
 
 (defun nrepl-default-err-handler (buffer ex root-ex session)
+  "Make an error handler for BUFFER, EX, ROOT-EX and SESSION."
   ;; TODO: use ex and root-ex as fallback values to display when pst/print-stack-trace-not-found
   (if (or nrepl-popup-stacktraces
           (not (member (buffer-local-value 'major-mode buffer) '(nrepl-mode clojure-mode))))
@@ -776,6 +812,7 @@ Removes any leading slash if on Windows.  Uses `find-file'."
     (substring-no-properties (buffer-string))))
 
 (defun nrepl-need-input (buffer)
+  "Handle an need-input request from BUFFER."
   (with-current-buffer buffer
     (nrepl-send-stdin (concat (read-from-minibuffer "Stdin: ") "\n")
                       (nrepl-stdin-handler buffer))))
@@ -793,7 +830,8 @@ Removes any leading slash if on Windows.  Uses `find-file'."
    "The function that is used to quit a temporary popup buffer."))
 
 (defun nrepl-popup-buffer-quit-function (&optional kill-buffer-p)
-  "Wrapper to invoke the value of `nrepl-popup-buffer-quit-function'."
+  "Wrapper to invoke the function `nrepl-popup-buffer-quit-function'.
+KILL-BUFFER-P is passed along."
   (interactive)
   (funcall nrepl-popup-buffer-quit-function kill-buffer-p))
 
@@ -825,7 +863,7 @@ If prefix argument KILL-BUFFER-P is non-nil, kill the buffer instead of burying
     (current-buffer)))
 
 (defun nrepl-emit-into-popup-buffer (buffer value)
-  "Insert VALUE into BUFFER."
+  "Emit into BUFFER the provided VALUE."
   (with-current-buffer buffer
     (let ((inhibit-read-only t)
           (buffer-undo-list t))
@@ -834,6 +872,7 @@ If prefix argument KILL-BUFFER-P is non-nil, kill the buffer instead of burying
       (font-lock-fontify-buffer))))
 
 (defun nrepl-emit-into-color-buffer (buffer value)
+  "Emit into color BUFFER the provided VALUE."
   (with-current-buffer buffer
     (let ((inhibit-read-only t)
           (buffer-undo-list t))
@@ -845,6 +884,8 @@ If prefix argument KILL-BUFFER-P is non-nil, kill the buffer instead of burying
 
 ;;;; Macroexpansion
 (defun nrepl-macroexpand-undo (&optional arg)
+  "Undo the last macroexpansion, using `undo-only'.
+ARG is passed along to `undo-only'."
   (interactive)
   (let ((inhibit-read-only t))
     (undo-only arg)))
@@ -854,6 +895,7 @@ If prefix argument KILL-BUFFER-P is non-nil, kill the buffer instead of burying
 This variable specifies both what was expanded and the expander.")
 
 (defun nrepl-macroexpand-handler (buffer ns)
+  "Make a response handler for macroexpansion from BUFFER in namespace NS."
   (lexical-let* ((ns ns))
     (nrepl-make-response-handler buffer nil
                                  (lambda (buffer str)
@@ -863,6 +905,8 @@ This variable specifies both what was expanded and the expander.")
 
 (defun nrepl-macroexpand-inplace-handler
   (expansion-buffer start end current-point)
+  "Make a response handler for inplace macroexpansion from EXPANSION-BUFFER.
+START, END and CURRENT-POINT are used to redraw the expansion."
   (lexical-let* ((start start)
                  (end end)
                  (current-point current-point))
@@ -874,20 +918,20 @@ This variable specifies both what was expanded and the expander.")
                                  nil nil)))
 
 (defun nrepl-macroexpand-form (expander expr)
+  "Macroexpand, using EXPANDER, the given EXPR."
   (format
    "(clojure.pprint/write (%s '%s) :suppress-namespaces true :dispatch clojure.pprint/code-dispatch)"
    expander expr))
 
 (defun nrepl-macroexpand-expr (expander expr &optional buffer)
-  "Evaluate the expression preceding point and print the result
-into the special buffer."
+  "Macroexpand, use EXPANDER, the given EXPR from BUFFER."
   (let ((form (nrepl-macroexpand-form expander expr)))
     (setq nrepl-last-macroexpand-expression form)
     (nrepl-send-string form (nrepl-macroexpand-handler buffer nrepl-buffer-ns)
                        nrepl-buffer-ns)))
 
 (defun nrepl-macroexpand-expr-inplace (expander)
-  "Substitutes the current form at point with its macroexpansion."
+  "Substitutes the current form at point with its macroexpansion using EXPANDER."
   (interactive)
   (let ((form-with-bounds (nrepl-sexp-at-point-with-bounds)))
     (if form-with-bounds
@@ -907,32 +951,34 @@ into the special buffer."
    nrepl-buffer-ns))
 
 (defun nrepl-macroexpand-1 (&optional prefix)
-  "Invoke 'macroexpand-1' on the expression preceding point and display the
-result in a macroexpansion buffer.
-If invoked with a prefix argument, use 'macroexpand' instead of
+  "Invoke 'macroexpand-1' on the expression at point.
+If invoked with a PREFIX argument, use 'macroexpand' instead of
 'macroexpand-1'."
   (interactive "P")
   (let ((expander (if prefix 'macroexpand 'macroexpand-1)))
     (nrepl-macroexpand-expr expander (nrepl-sexp-at-point))))
 
 (defun nrepl-macroexpand-1-inplace (&optional prefix)
+  "Perform inplace 'macroexpand-1' on the expression at point.
+If invoked with a PREFIX argument, use 'macroexpand' instead of
+'macroexpand-1'."
   (interactive "P")
   (let ((expander (if prefix 'macroexpand 'macroexpand-1)))
     (nrepl-macroexpand-expr-inplace expander)))
 
 (defun nrepl-macroexpand-all ()
-  "Invoke 'clojure.walk/macroexpand-all' on the expression
-preceding point and display the result in a macroexpansion
-buffer."
+  "Invoke 'clojure.walk/macroexpand-all' on the expression at point."
   (interactive)
   (nrepl-macroexpand-expr
    'clojure.walk/macroexpand-all (nrepl-sexp-at-point)))
 
 (defun nrepl-macroexpand-all-inplace ()
+  "Perform inplace 'clojure.walk/macroexpand-all' on the expression at point."
   (interactive)
   (nrepl-macroexpand-expr-inplace 'clojure.walk/macroexpand-all))
 
 (defun nrepl-initialize-macroexpansion-buffer (expansion ns)
+  "Create a new Macroexpansion buffer with EXPANSION and namespace NS."
   (pop-to-buffer (nrepl-create-macroexpansion-buffer))
   (setq nrepl-buffer-ns ns)
   (setq buffer-undo-list nil)
@@ -944,6 +990,9 @@ buffer."
     (font-lock-fontify-buffer)))
 
 (defun nrepl-redraw-macroexpansion-buffer (expansion buffer start end current-point)
+  "Redraw the macroexpansion with new EXPANSION.
+Text in BUFFER from START to END is replaced with new expansion,
+and point is placed at CURRENT-POINT."
   (with-current-buffer buffer
     (let ((buffer-read-only nil))
       (goto-char start)
@@ -955,28 +1004,28 @@ buffer."
 
 
 (defun nrepl-popup-eval-print (form)
-  "Evaluate the given form and print value in current buffer."
+  "Evaluate the given FORM and print value in current buffer."
   (let ((buffer (current-buffer)))
     (nrepl-send-string form
                        (nrepl-popup-eval-print-handler buffer)
                        nrepl-buffer-ns)))
 
 (defun nrepl-interactive-eval-print (form)
-  "Evaluate the given form and print value in current buffer."
+  "Evaluate the given FORM and print value in current buffer."
   (let ((buffer (current-buffer)))
     (nrepl-send-string form
                        (nrepl-interactive-eval-print-handler buffer)
                        nrepl-buffer-ns)))
 
 (defun nrepl-interactive-eval (form)
-  "Evaluate the given form and print value in minibuffer."
+  "Evaluate the given FORM and print value in minibuffer."
   (let ((buffer (current-buffer)))
     (nrepl-send-string form
                        (nrepl-interactive-eval-handler buffer)
                        nrepl-buffer-ns)))
 
 (defun nrepl-send-op (op attributes handler)
-  "Send the specified op."
+  "Send the specified OP with ATTRIBUTES and response HANDLER."
   (let ((buffer (current-buffer)))
     (nrepl-send-request (append
                          (list "op" op
@@ -986,7 +1035,9 @@ buffer."
                         handler)))
 
 (defun nrepl-send-load-file (file-contents file-path file-name)
-  "Evaluate the given form and print value in minibuffer."
+  "Perform the nREPL \"load-file\" op.
+FILE-CONTENTS, FILE-PATH and FILE-NAME are details of the file to be
+loaded."
   (let ((buffer (current-buffer)))
     (nrepl-send-request (list "op" "load-file"
                               "session" (nrepl-current-session)
@@ -996,7 +1047,8 @@ buffer."
                         (nrepl-load-file-handler buffer))))
 
 (defun nrepl-eval-last-expression (&optional prefix)
-  "Evaluate the expression preceding point."
+  "Evaluate the expression preceding point.
+If invoked with a PREFIX argument, print the result in the current buffer."
   (interactive "P")
   (if prefix
       (nrepl-interactive-eval-print (nrepl-last-expression))
@@ -1050,11 +1102,13 @@ Empty strings and duplicates are ignored."
   (delete-region nrepl-input-start-mark (point-max)))
 
 (defun nrepl-replace-input (string)
+  "Replace the current repl input with STRING."
   (nrepl-delete-current-input)
   (insert-and-inherit string))
 
 (defun nrepl-position-in-history (start-pos direction regexp)
-  "Return the position of the history item matching regexp.
+  "Return the position of the history item starting at START-POS.
+Search in DIRECTION for REGEXP.
 Return -1 resp. the length of the history if no item matches"
   ;; Loop through the history list looking for a matching line
   (let* ((step (ecase direction
@@ -1097,9 +1151,11 @@ If REGEXP is non-nil, only lines matching REGEXP are considered."
     (setq this-command 'nrepl-history-replace)))
 
 (defun nrepl-history-search-in-progress-p ()
+  "Return t if a current history search is in progress."
   (eq last-command 'nrepl-history-replace))
 
 (defun nrepl-terminate-history-search ()
+  "Terminate the current history search."
   (setq last-command this-command))
 
 (defun nrepl-previous-input ()
@@ -1127,17 +1183,20 @@ See `nrepl-previous-input'."
   (nrepl-history-replace 'backward (nrepl-history-pattern)))
 
 (defun nrepl-previous-matching-input (regexp)
+  "Find the previous input matching REGEXP."
   (interactive "sPrevious element matching (regexp): ")
   (nrepl-terminate-history-search)
   (nrepl-history-replace 'backward regexp))
 
 (defun nrepl-next-matching-input (regexp)
+  "Find then next input matching REGEXP."
   (interactive "sNext element matching (regexp): ")
   (nrepl-terminate-history-search)
   (nrepl-history-replace 'forward regexp))
 
 (defun nrepl-history-pattern (&optional use-current-input)
-  "Return the regexp for the navigation commands."
+  "Return the regexp for the navigation commands.
+If USE-CURRENT-INPUT is non-nil, use the current input."
   (cond ((nrepl-history-search-in-progress-p)
          nrepl-history-pattern)
         (use-current-input
@@ -1166,7 +1225,7 @@ See `nrepl-previous-input'."
                   nrepl-history-file))
 
 (defun nrepl-history-read (filename)
-  "Read history from FILE and return it.
+  "Read history from FILENAME and return it.
 Does not yet set the input history."
   (if (file-readable-p filename)
       (with-temp-buffer
@@ -1226,6 +1285,7 @@ This function is meant to be used in hooks to avoid lambda
 ;; new items with the current history found in the file, which may
 ;; have been changed in the meantime by another session
 (defun nrepl-histories-merge (session-hist n-added-items file-hist)
+  "Merge histories from SESSION-HIST adding N-ADDED-ITEMS into FILE-HIST."
   (append (subseq session-hist 0 n-added-items)
           file-hist))
 
@@ -1256,7 +1316,8 @@ This function is meant to be used in hooks to avoid lambda
   (nrepl-bol-internal))
 
 (defun nrepl-at-prompt-start-p ()
-  ;; This will not work on non-current prompts.
+  "Return t if point is at the start of prompt.
+This will not work on non-current prompts."
   (= (point) nrepl-input-start-mark))
 
 ;;; mode book-keeping
@@ -1336,6 +1397,7 @@ This function is meant to be used in hooks to avoid lambda
   nrepl-macroexpansion-minor-mode-map)
 
 (defun nrepl-create-macroexpansion-buffer ()
+  "Create a new macroexpansion buffer."
   (with-current-buffer (nrepl-popup-buffer nrepl-macroexpansion-buffer t)
     (clojure-mode)
     (clojure-disable-nrepl)
@@ -1395,12 +1457,12 @@ This function is meant to be used in hooks to avoid lambda
     ["Interrupt" nrepl-interrupt]))
 
 (defun clojure-enable-nrepl ()
-  "Enable `nrepl-interaction-mode'.
+  "Turn on nrepl interaction mode (see command `nrepl-interaction-mode').
 Useful in hooks."
   (nrepl-interaction-mode 1))
 
 (defun clojure-disable-nrepl ()
-  "Disable `nrepl-interaction-mode'.
+  "Turn off nrepl interaction mode (see command `nrepl-interaction-mode').
 Useful in hooks."
   (nrepl-interaction-mode -1))
 
@@ -1452,7 +1514,7 @@ Useful in hooks."
           (locate-file (format "%s.bat" nrepl-lein-command) exec-path))
       (format "%s repl :headless" nrepl-lein-command)
     (format "echo \"%s repl :headless\" | eval $SHELL -l" nrepl-lein-command))
-  "The command used to start the nREPL via nrepl-jack-in.
+  "The command used to start the nREPL via command `nrepl-jack-in'.
 For a remote nREPL server lein must be in your PATH.  The remote
 proc is launched via sh rather than bash, so it might be necessary
 to specific the full path to it. Localhost is assumed."
@@ -1470,6 +1532,7 @@ to specific the full path to it. Localhost is assumed."
           (recenter -1))))))
 
 (defmacro nrepl-save-marker (marker &rest body)
+  "Save MARKER and execute BODY."
   (let ((pos (make-symbol "pos")))
     `(let ((,pos (marker-position ,marker)))
        (prog1 (progn . ,body)
@@ -1496,7 +1559,8 @@ Return the position of the prompt beginning."
         prompt-start))))
 
 (defun nrepl-emit-output-at-pos (buffer string position &optional bol)
-  ;; insert STRING and mark it as output
+  "Using BUFFER, insert STRING at POSITION and mark it as output.
+If BOL is non-nil insert at the beginning of line."
   (with-current-buffer buffer
     (save-excursion
       (nrepl-save-marker nrepl-output-start
@@ -1513,15 +1577,19 @@ Return the position of the prompt beginning."
     (nrepl-show-maximum-output)))
 
 (defun nrepl-emit-interactive-output (string)
+  "Emit STRING as interactive output."
   (with-current-buffer (nrepl-current-connection-buffer)
     (nrepl-emit-output-at-pos
      (current-buffer) string (1- (nrepl-input-line-beginning-position)) t)))
 
 (defun nrepl-emit-output (buffer string &optional bol)
+  "Using BUFFER, emit STRING.
+If BOL is non-nil, emit at the beginning of the line."
   (with-current-buffer buffer
     (nrepl-emit-output-at-pos buffer string nrepl-input-start-mark bol)))
 
 (defun nrepl-emit-prompt (buffer)
+  "Emit the repl prompt into BUFFER."
   (with-current-buffer buffer
     (save-excursion
       (nrepl-save-marker nrepl-output-start
@@ -1530,7 +1598,8 @@ Return the position of the prompt beginning."
     (nrepl-show-maximum-output)))
 
 (defun nrepl-emit-result (buffer string &optional bol)
-  ;; insert STRING and mark it as evaluation result
+  "Emit into BUFFER the result STRING and mark it as an evaluation result.
+If BOL is non-nil insert at the beginning of the line."
   (with-current-buffer buffer
     (save-excursion
       (nrepl-save-marker nrepl-output-start
@@ -1543,14 +1612,15 @@ Return the position of the prompt beginning."
     (nrepl-show-maximum-output)))
 
 (defun nrepl-default-handler (response)
-  "Default handler which is invoked when no handler is found."
+  "Default handler which is invoked when no handler is found.
+Handles message contained in RESPONSE."
   (nrepl-dbind-response response (out value)
     (cond
      (out
       (nrepl-emit-interactive-output out)))))
 
 (defun nrepl-dispatch (response)
-  "Dispatch the response to associated callback."
+  "Dispatch the RESPONSE to associated callback."
   (nrepl-dbind-response response (id)
     (let ((callback (gethash id nrepl-requests)))
       (if callback
@@ -1558,8 +1628,8 @@ Return the position of the prompt beginning."
         (nrepl-default-handler response)))))
 
 (defun nrepl-net-decode ()
-  "Decode the data in the current buffer and remove the processed data from the
-buffer if the decode successful."
+  "Decode the data in the current buffer.
+Remove the processed data from the buffer if the decode successful."
   (let* ((start (point-min))
          (end (point-max))
          (data (buffer-substring start end)))
@@ -1568,7 +1638,7 @@ buffer if the decode successful."
       (delete-region start end))))
 
 (defun nrepl-net-process-input (process)
-  "Process all complete messages.
+  "Handle all complete messages from PROCESS.
 Assume that any error during decoding indicates an incomplete message."
   (with-current-buffer (process-buffer process)
     (ignore-errors
@@ -1578,13 +1648,16 @@ Assume that any error during decoding indicates an incomplete message."
             (nrepl-dispatch response)))))))
 
 (defun nrepl-net-filter (process string)
-  "Decode the message(s) and dispatch."
+  "Decode the message(s) from PROCESS contained in STRING and dispatch."
   (with-current-buffer (process-buffer process)
     (goto-char (point-max))
     (insert string))
   (nrepl-net-process-input process))
 
 (defun nrepl-sentinel (process message)
+  "Handle sentinel events from PROCESS.
+Display MESSAGE and if the process is closed kill the
+process buffer and run the hook `nrepl-disconnected-hook'."
   (message "nrepl connection closed: %s" message)
   (if (equal (process-status process) 'closed)
       (progn
@@ -1592,23 +1665,26 @@ Assume that any error during decoding indicates an incomplete message."
         (run-hooks 'nrepl-disconnected-hook))))
 
 (defun nrepl-write-message (process message)
+  "Send the PROCESS the MESSAGE."
   (process-send-string process message))
 
 ;;; repl interaction
 (defun nrepl-property-bounds (prop)
-  "Return two the positions of the previous and next changes to PROP.
- PROP is the name of a text property."
+  "Return the the positions of the previous and next change to PROP.
+PROP is the name of a text property."
   (assert (get-text-property (point) prop))
   (let ((end (next-single-char-property-change (point) prop)))
     (list (previous-single-char-property-change end prop) end)))
 
 (defun nrepl-in-input-area-p ()
+  "Return t if in input area."
   (<= nrepl-input-start-mark (point)))
 
 (defun nrepl-current-input (&optional until-point-p)
   "Return the current input as string.
 The input is the region from after the last prompt to the end of
-buffer."
+buffer.  If UNTIL-POINT-P is non-nil, the input is until the current
+point."
   (buffer-substring-no-properties nrepl-input-start-mark
                                   (if until-point-p
                                       (point)
@@ -1625,6 +1701,8 @@ buffer."
   (nrepl-find-prompt))
 
 (defun nrepl-find-prompt (&optional backward)
+  "Find the next prompt.
+If BACKWARD is non-nil look backward."
   (let ((origin (point))
         (prop 'nrepl-prompt))
     (while (progn
@@ -1634,23 +1712,29 @@ buffer."
       (goto-char origin))))
 
 (defun nrepl-search-property-change (prop &optional backward)
+  "Search forward for a property change to PROP.
+If BACKWARD is non-nil search backward."
   (cond (backward
          (goto-char (previous-single-char-property-change (point) prop)))
         (t
          (goto-char (next-single-char-property-change (point) prop)))))
 
 (defun nrepl-end-of-proprange-p (property)
+  "Return t if at the the end of a property range for PROPERTY."
   (and (get-char-property (max 1 (1- (point))) property)
        (not (get-char-property (point) property))))
 
 (defun nrepl-mark-input-start ()
+  "Mark the input start."
   (set-marker nrepl-input-start-mark (point) (current-buffer)))
 
 (defun nrepl-mark-output-start ()
+  "Mark the output start."
   (set-marker nrepl-output-start (point))
   (set-marker nrepl-output-end (point)))
 
 (defun nrepl-mark-output-end ()
+  "Marke the output end."
   (add-text-properties nrepl-output-start nrepl-output-end
                        '(face nrepl-output-face
                               rear-nonsticky (face))))
@@ -1661,14 +1745,14 @@ buffer."
 ;;; server.
 
 (defvar nrepl-connection-dispatch nil
- "Bound to the connection a message was received on, for the
-  duration of the handling of that message")
+  "Bound to the connection a message was received on.
+This is bound for the duration of the handling of that message")
 
 (defvar nrepl-connection-list nil
-  "A list of connections")
+  "A list of connections.")
 
 (defun nrepl-make-connection-buffer ()
-  "Create an nREPL connection buffer"
+  "Create an nREPL connection buffer."
   (let ((buffer (generate-new-buffer "*nrepl-connection*")))
     (with-current-buffer buffer
       (buffer-disable-undo)
@@ -1676,19 +1760,19 @@ buffer."
     buffer))
 
 (defun nrepl-current-connection-buffer ()
-  "The connection to use for nREPL interaction"
+  "The connection to use for nREPL interaction."
   (or nrepl-connection-dispatch
       nrepl-connection-buffer
       (car nrepl-connection-list)))
 
 (defun nrepl-current-nrepl-buffer ()
-  "The current nrepl buffer"
+  "The current nrepl buffer."
   (when (nrepl-current-connection-buffer)
     (buffer-local-value 'nrepl-nrepl-buffer
                         (get-buffer (nrepl-current-connection-buffer)))))
 
 (defun nrepl-make-repl-connection-default (connection-buffer)
-  "Makes an nREPL connection the default connection"
+  "Make the nREPL CONNECTION-BUFFER the default connection."
   (interactive (list nrepl-connection-buffer))
   (if connection-buffer
       ;; maintain the connection list in most recently used order
@@ -1700,40 +1784,53 @@ buffer."
 ;;; server messages
 
 (defun nrepl-current-session ()
+  "Return the current session."
   (with-current-buffer (nrepl-current-connection-buffer)
     nrepl-session))
 
 (defun nrepl-current-tooling-session ()
+  "Return the current tooling session."
   (with-current-buffer (nrepl-current-connection-buffer)
     nrepl-tooling-session))
 
 (defun nrepl-next-request-id ()
+  "Return the next request id."
   (with-current-buffer (nrepl-current-connection-buffer)
     (number-to-string (incf nrepl-request-counter))))
 
 (defun nrepl-send-request (request callback)
+  "Send REQUEST and register response handler CALLBACK."
   (let* ((request-id (nrepl-next-request-id))
          (message (nrepl-bencode (append (list "id" request-id) request))))
     (puthash request-id callback nrepl-requests)
     (nrepl-write-message (nrepl-current-connection-buffer) message)))
 
 (defun nrepl-create-client-session (callback)
+  "Sent a request to create a new client session.
+Response will be handled by CALLBACK."
   (nrepl-send-request '("op" "clone")
                       callback))
 
 (defun nrepl-send-stdin (input callback)
+  "Send a stdin message with INPUT.
+Register CALLBACK as the response handler."
   (nrepl-send-request (list "op" "stdin"
                             "stdin" input
                             "session" (nrepl-current-session))
                       callback))
 
 (defun nrepl-send-interrupt (pending-request-id callback)
+  "Send an interrupt message for PENDING-REQUEST-ID.
+Register CALLBACK as the response handler."
   (nrepl-send-request (list "op" "interrupt"
                             "session" (nrepl-current-session)
                             "interrupt-id" pending-request-id)
                       callback))
 
 (defun nrepl-eval-request (input &optional ns session)
+  "Send a request to eval INPUT.
+If NS is non-nil, include it in the request.
+Use SESSION if it is non-nil, otherwise use the current session."
   (append (if ns (list "ns" ns))
           (list
            "op" "eval"
@@ -1741,9 +1838,12 @@ buffer."
            "code" input)))
 
 (defun nrepl-send-string (input callback &optional ns session)
+  "Send the request INPUT and register the CALLBACK as the response handler.
+See command `nrepl-eval-request' for details on how NS and SESSION are processed."
   (nrepl-send-request (nrepl-eval-request input ns session) callback))
 
 (defun nrepl-sync-request-handler (buffer)
+  "Make a synchronous request handler for BUFFER."
   (nrepl-make-response-handler buffer
                                (lambda (buffer value)
                                  (setq nrepl-sync-response
@@ -1763,7 +1863,7 @@ buffer."
                                        (plist-put nrepl-sync-response :done t)))))
 
 (defun nrepl-send-request-sync (request)
-  "Send a request to the backend synchronously (discouraged).
+  "Send REQUEST to the backend synchronously (discouraged).
 The result is a plist with keys :value, :stderr and :stdout."
   (with-current-buffer (nrepl-current-connection-buffer)
     (setq nrepl-sync-response nil)
@@ -1774,6 +1874,9 @@ The result is a plist with keys :value, :stderr and :stdout."
     nrepl-sync-response))
 
 (defun nrepl-send-string-sync (input &optional ns session)
+  "Send the INPUT the the backed synchronously.
+See command `nrepl-eval-request' for details about how NS and SESSION
+are processed."
   (nrepl-send-request-sync (nrepl-eval-request input ns session)))
 
 (defalias 'nrepl-eval 'nrepl-send-string-sync)
@@ -1822,7 +1925,7 @@ earlier in the buffer."
 (defun nrepl-indent-and-complete-symbol ()
   "Indent the current line and perform symbol completion.
 First indent the line. If indenting doesn't move point, complete
-the symbol. "
+the symbol."
   (interactive)
   (let ((pos (point)))
     (lisp-indent-line)
@@ -1839,7 +1942,7 @@ the symbol. "
          (nrepl-delete-current-input))))
 
 (defun nrepl-input-complete-p (start end)
-  "Return t if the region from START to END contains a complete sexp."
+  "Return t if the region from START to END is a complete sexp."
   (save-excursion
     (goto-char start)
     (cond ((looking-at "\\s *[@'`#]?[(\"]")
@@ -1859,7 +1962,7 @@ the symbol. "
   "Evaluate the current input string, or insert a newline.
 Send the current input ony if a whole expression has been entered,
 i.e. the parenthesis are matched.
-With prefix argument send the input even if the parenthesis are not
+With prefix END-OF-INPUT argument send the input even if the parenthesis are not
 balanced."
   (interactive "P")
   (cond
@@ -1884,7 +1987,7 @@ balanced."
 
 (defun nrepl-grab-old-input (replace)
   "Resend the old REPL input at point.
-If replace is non-nil the current input is replaced with the old
+If REPLACE is non-nil the current input is replaced with the old
 input; otherwise the new input is appended.  The old input has the
 text property `nrepl-old-input'."
   (multiple-value-bind (beg end) (nrepl-property-bounds 'nrepl-old-input)
@@ -1934,8 +2037,8 @@ text property `nrepl-old-input'."
   (run-hooks 'nrepl-clear-buffer-hook))
 
 (defun nrepl-find-and-clear-repl-buffer ()
-  "Finds the `nrepl-nrepl-buffer`, clears it and returns to the
-buffer in which the command was invoked."
+  "Find the `nrepl-nrepl-buffer` and clears it.
+Returns to the buffer in which the command was invoked."
   (interactive)
   (let ((origin-buffer (current-buffer)))
     (switch-to-buffer (nrepl-current-nrepl-buffer))
@@ -1943,6 +2046,7 @@ buffer in which the command was invoked."
     (switch-to-buffer origin-buffer)))
 
 (defun nrepl-input-line-beginning-position ()
+  "Return the position of the beginning of input."
   (save-excursion
     (goto-char nrepl-input-start-mark)
     (line-beginning-position)))
@@ -1965,6 +2069,7 @@ buffer in which the command was invoked."
            (propertize ";;; output cleared" 'face 'font-lock-comment-face)))))))
 
 (defun nrepl-find-ns ()
+  "Return the ns specified in the buffer, or \"user\" if no ns declaration is found."
   (or (save-restriction
         (widen)
         (clojure-find-ns))
@@ -1972,8 +2077,8 @@ buffer in which the command was invoked."
 
 (defun nrepl-current-ns ()
   "Return the ns in the current context.
- If `nrepl-buffer-ns' has a value then return that, otherwise
- search for and read a `ns' form."
+If `nrepl-buffer-ns' has a value then return that, otherwise
+search for and read a `ns' form."
   (let ((ns nrepl-buffer-ns))
     (or (and (string= ns "user")
              (nrepl-find-ns))
@@ -2033,6 +2138,8 @@ buffer in which the command was invoked."
   (nrepl-insert-prompt ns))
 
 (defun nrepl-init-repl-buffer (connection buffer &optional noprompt)
+  "Initialize the repl for CONNECTION in BUFFER.
+Insert a banner, unless NOPROMPT is non-nil."
   (with-current-buffer buffer
     (unless (eq major-mode 'nrepl-mode)
       (nrepl-mode))
@@ -2041,7 +2148,7 @@ buffer in which the command was invoked."
       (nrepl-insert-banner nrepl-buffer-ns))
     (current-buffer)))
 
-(defun nrepl-repl-buffer (&optional noprompt)
+(defun nrepl-repl-buffer ()
   "Return the repl buffer, create if necessary."
   (let ((buffer (get-buffer (nrepl-current-nrepl-buffer))))
     (or (if (buffer-live-p buffer) buffer)
@@ -2062,7 +2169,7 @@ the buffer should appear."
     (goto-char (point-max))))
 
 (defun nrepl-set-ns (ns)
-  "Switch the namespace of the nREPL buffer to ns."
+  "Switch the namespace of the nREPL buffer to NS."
   (interactive (list (nrepl-current-ns)))
   (with-current-buffer (nrepl-current-nrepl-buffer)
     (nrepl-send-string
@@ -2080,6 +2187,7 @@ the buffer should appear."
 (defvar nrepl-ido-ns nil)
 
 (defun nrepl-ido-form (ns)
+  "Construct a clojure form for ido read using NS."
   `(concat (if (find-ns (symbol ,ns))
                (map name (concat (keys (ns-interns (symbol ,ns)))
                                  (keys (ns-refers (symbol ,ns))))))
@@ -2095,9 +2203,11 @@ the buffer should appear."
              (into (hash-set)))))
 
 (defun nrepl-ido-up-ns (ns)
+  "Perform up using NS."
   (mapconcat 'identity (butlast (split-string ns "\\.")) "."))
 
 (defun nrepl-ido-select (selected targets callback)
+  "Peform ido select using SELECTED, TARGETS and CALLBACK."
   ;; TODO: immediate RET gives "" as selected for some reason
   ;; this is an OK workaround though
   (cond ((equal "" selected)
@@ -2110,6 +2220,7 @@ the buffer should appear."
         (t (funcall callback selected))))
 
 (defun nrepl-ido-read-var-handler (ido-callback buffer)
+  "Create an ido read var handler with IDO-CALLBACK for BUFFER."
   (lexical-let ((ido-callback ido-callback))
     (nrepl-make-response-handler buffer
                                  (lambda (buffer value)
@@ -2121,6 +2232,7 @@ the buffer should appear."
                                  nil nil nil)))
 
 (defun nrepl-ido-read-var (ns ido-callback)
+  "Perform ido read var in NS using IDO-CALLBACK."
   ;; Have to be stateful =(
   (setq nrepl-ido-ns ns)
   (nrepl-send-string (prin1-to-string (nrepl-ido-form nrepl-ido-ns))
@@ -2128,17 +2240,11 @@ the buffer should appear."
                      nrepl-buffer-ns
                      (nrepl-current-tooling-session)))
 
-(defun nrepl-operator-before-point ()
-  (ignore-errors
-    (save-excursion
-      (backward-up-list 1)
-      (down-list 1)
-      (nrepl-symbol-at-point))))
-
 (defun nrepl-read-symbol-name (prompt callback &optional query)
-  "Either read a symbol name or choose the one at point.
-The user is prompted if a prefix argument is in effect, if there is no
-symbol at point, or if QUERY is non-nil."
+  "Either read a symbol name using PROMPT or choose the one at point.
+Use CALLBACK as the ido read var callback.
+The user is prompted with PROMPT if a prefix argument is in effect,
+if there is no symbol at point, or if QUERY is non-nil."
   (let ((symbol-name (nrepl-symbol-at-point)))
     (cond ((not (or current-prefix-arg query (not symbol-name)))
            (funcall callback symbol-name))
@@ -2146,6 +2252,7 @@ symbol at point, or if QUERY is non-nil."
           (t (funcall callback (read-from-minibuffer prompt symbol-name))))))
 
 (defun nrepl-doc-handler (symbol)
+  "Create a handler to lookup documentation for SYMBOL."
   (let ((form (format "(clojure.repl/doc %s)" symbol))
         (doc-buffer (nrepl-popup-buffer nrepl-doc-buffer t)))
     (nrepl-send-string form
@@ -2161,6 +2268,7 @@ under point, prompts for a var."
   (nrepl-read-symbol-name "Symbol: " 'nrepl-doc-handler query))
 
 (defun nrepl-src-handler (symbol)
+  "Create a handler to lookup source for SYMBOL."
   (let ((form (format "(clojure.repl/source %s)" symbol))
         (src-buffer (nrepl-popup-buffer nrepl-src-buffer t)))
     (with-current-buffer src-buffer
@@ -2180,6 +2288,7 @@ under point, prompts for a var."
 
 ;; TODO: implement reloading ns
 (defun nrepl-eval-load-file (form)
+  "Load FORM."
   (let ((buffer (current-buffer)))
     (nrepl-send-string form (nrepl-interactive-eval-handler buffer))))
 
@@ -2189,11 +2298,13 @@ under point, prompts for a var."
     (buffer-string)))
 
 (defun nrepl-load-file-op (filename)
+  "Send \"load-file\" op for FILENAME."
   (nrepl-send-load-file (nrepl-file-string filename)
                         filename
                         (file-name-nondirectory filename)))
 
 (defun nrepl-load-file-core (filename)
+  "Load the clojure file FILENAME."
   (let ((fn (replace-regexp-in-string
              "\\\\" "\\\\\\\\"
              (convert-standard-filename (expand-file-name filename)))))
@@ -2202,6 +2313,7 @@ under point, prompts for a var."
              fn (nrepl-find-ns)))))
 
 (defun nrepl-dispatch-load-file (filename)
+  "Dispatch the load file operation for FILENAME."
   (if (nrepl-op-supported-p "load-file")
       (nrepl-load-file-op filename)
     (nrepl-load-file-core filename)))
@@ -2230,9 +2342,11 @@ under point, prompts for a var."
 
 ;;; interrupt
 (defun nrepl-interrupt-handler (buffer)
+  "Create an interrupt response handler for BUFFER."
   (nrepl-make-response-handler buffer nil nil nil nil))
 
 (defun nrepl-hash-keys (hashtable)
+  "Return a list of keys in HASHTABLE."
   (let ((keys '()))
     (maphash (lambda (k v) (setq keys (cons k keys))) hashtable)
     keys))
@@ -2246,6 +2360,7 @@ under point, prompts for a var."
 
 ;;; server
 (defun nrepl-server-filter (process output)
+  "Process nREPL server output from PROCESS contained in OUTPUT."
   (with-current-buffer (process-buffer process)
     (save-excursion
       (goto-char (point-max))
@@ -2265,6 +2380,7 @@ under point, prompts for a var."
                  'nrepl-project-dir (process-buffer process))))))))
 
 (defun nrepl-server-sentinel (process event)
+  "Handle nREPL server PROCESS EVENT."
   (let* ((b (process-buffer process))
          (connection-buffer (buffer-local-value 'nrepl-connection-buffer b))
          (problem (if (and b (buffer-live-p b))
@@ -2285,7 +2401,8 @@ under point, prompts for a var."
 
 ;;;###autoload
 (defun nrepl-enable-on-existing-clojure-buffers ()
-  "Enable `nrepl-interaction-mode' on existing Clojure buffers."
+  "Enable interaction mode on existing Clojure buffers.
+See command `nrepl-interaction-mode'."
   (interactive)
   (add-hook 'clojure-mode-hook 'clojure-enable-nrepl)
   (add-hook 'clojurescript-mode-hook 'clojure-enable-nrepl)
@@ -2298,7 +2415,8 @@ under point, prompts for a var."
 
 ;;;###autoload
 (defun nrepl-disable-on-existing-clojure-buffers ()
-  "Disable `nrepl-interaction-mode' on existing Clojure buffers."
+  "Disable interaction mode on existing Clojure buffers.
+See command `nrepl-interaction-mode'."
   (interactive)
   (save-window-excursion
     (dolist (buffer (buffer-list))
@@ -2309,6 +2427,7 @@ under point, prompts for a var."
           (clojure-disable-nrepl))))))
 
 (defun nrepl-possibly-disable-on-existing-clojure-buffers ()
+  "If not connected, disable nrepl interaction mode on existing clojure buffers."
   (when (not (nrepl-current-connection-buffer))
     (nrepl-disable-on-existing-clojure-buffers)))
 
@@ -2338,18 +2457,21 @@ start the server."
         (message "Starting nREPL server...")))))
 
 (defun nrepl-current-dir ()
+  "Return the directory of the current buffer."
   (lexical-let ((file-name (buffer-file-name (current-buffer))))
     (or (when file-name
           (file-name-directory file-name))
         list-buffers-directory)))
 
 (defun nrepl-project-directory-for (dir-name)
-  "Return the project directory for the specified dir-name, which may be "
+  "Return the project directory for the specified DIR-NAME."
   (when dir-name
     (locate-dominating-file dir-name "project.clj")))
 
 (defun nrepl-check-for-nrepl-buffer (endpoint project-directory)
   "Check whether `nrepl-nrepl-buffer' already exists.
+Looks for buffers where `nrepl-endpoint' matches ENDPOINT,
+or `nrepl-project-dir' matches PROJECT-DIRECTORY.
 If so ask the user for confirmation."
   (if (find-if
        (lambda (buffer)
@@ -2362,10 +2484,11 @@ If so ask the user for confirmation."
                            (buffer-local-value 'nrepl-project-dir buffer))))))
        nrepl-connection-list)
       (y-or-n-p
-       "An nREPL buffer already exists. Do you really want to create a new one?")
+       "An nREPL buffer already exists. Do you really want to create a new one? ")
     t))
 
 (defun nrepl--close-buffer (buffer)
+  "Close the nrepl BUFFER."
   (message "Close buffer %s" buffer)
   (when (get-buffer-process buffer)
     (delete-process (get-buffer-process buffer)))
@@ -2373,7 +2496,7 @@ If so ask the user for confirmation."
     (kill-buffer buffer)))
 
 (defun nrepl-close-ancilliary-buffers ()
-  "Closes buffers that are shared across connections"
+  "Closes buffers that are shared across connections."
   (interactive)
   (dolist (buf-name `(,nrepl-error-buffer
                       ,nrepl-doc-buffer
@@ -2382,7 +2505,7 @@ If so ask the user for confirmation."
     (nrepl--close-buffer buf-name)))
 
 (defun nrepl-close (connection-buffer)
-  "Close an nrepl connection."
+  "Close the nrepl connection for CONNECTION-BUFFER."
   (interactive (list (nrepl-current-connection-buffer)))
   (let ((nrepl-connection-dispatch connection-buffer))
     (lexical-let ((buffer (get-buffer connection-buffer)))
@@ -2413,12 +2536,13 @@ restart the server."
 
 ;;; client
 (defun nrepl-op-supported-p (op)
-  "Return t iff the given operation is supported by nREPL server."
+  "Return t iff the given operation OP is supported by nREPL server."
   (with-current-buffer (nrepl-current-connection-buffer)
     (if (and nrepl-ops (assoc op nrepl-ops))
         t)))
 
 (defun nrepl-describe-handler (process-buffer)
+  "Return a handler to describe into PROCESS-BUFFER."
   (lexical-let ((buffer process-buffer))
     (lambda (response)
       (nrepl-dbind-response response (ops)
@@ -2427,11 +2551,13 @@ restart the server."
                  (setq nrepl-ops ops))))))))
 
 (defun nrepl-describe-session (process)
+  "Peform describe for the given server PROCESS."
   (let ((buffer (process-buffer process)))
     (nrepl-send-request (list "op" "describe")
                         (nrepl-describe-handler buffer))))
 
 (defun nrepl-create-nrepl-buffer (process)
+  "Create a repl buffer for PROCESS."
   (nrepl-init-repl-buffer
    process
    (let ((buf (generate-new-buffer-name "*nrepl*")))
@@ -2439,6 +2565,7 @@ restart the server."
      buf)))
 
 (defun nrepl-new-tooling-session-handler (process)
+  "Create a new tooling session handler for PROCESS."
   (lexical-let ((process process))
     (lambda (response)
       (nrepl-dbind-response response (id new-session)
@@ -2448,6 +2575,7 @@ restart the server."
                  (remhash id nrepl-requests))))))))
 
 (defun nrepl-new-session-handler (process)
+  "Create a new session handler for PROCESS."
   (lexical-let ((process process))
     (lambda (response)
       (nrepl-dbind-response response (id new-session)
@@ -2468,6 +2596,7 @@ restart the server."
                  (run-hooks 'nrepl-connected-hook))))))))
 
 (defun nrepl-init-client-sessions (process)
+  "Initialize client sessions for PROCESS."
   (nrepl-create-client-session (nrepl-new-session-handler process))
   (nrepl-create-client-session (nrepl-new-tooling-session-handler process)))
 
@@ -2496,6 +2625,7 @@ restart the server."
 
 ;;;###autoload
 (defun nrepl (host port)
+  "Connect nrepl to HOST and PORT."
   (interactive (list (read-string "Host: " nrepl-host nil nrepl-host)
                      (string-to-number (read-string "Port: " nrepl-port nil nrepl-port))))
   (when (nrepl-check-for-nrepl-buffer `(,host ,port) nil)