Fix checkdoc errors in pdf-tools lisp code

- Add / Fix docstrings for functions.
- Make punctuation changes as suggested by `checkdoc`

This commit makes changes in a subset of files of `pdf-tools`. Some of
the major files are still pending changes, and will be addressed in a
later commit.

Partially Fixes: #64

7 files changed, 191 insertions, 57 deletions

diff --git a/lisp/pdf-annot.el b/lisp/pdf-annot.el
index 7217622..570e589 100644
--- a/lisp/pdf-annot.el
+++ b/lisp/pdf-annot.el
@@ -37,6 +37,8 @@
 ;; * Customizations
 ;; * ================================================================== *
 
+;;; Code:
+
 (defgroup pdf-annot nil
   "Annotation support for PDF documents."
   :group 'pdf-tools)
@@ -221,9 +223,9 @@ these arguments:
 
 `:changed' The list of recently changed annotations.
 
-`t' The union of recently added, deleted or changed annotations.
+t The union of recently added, deleted or changed annotations.
 
-`nil' Just returns nil.
+nil Just returns nil.
 
 Any other argument signals an error.")
 
@@ -246,8 +248,10 @@ no effect on the rendering.")
   "A list of standard icon properties for text annotations.")
 
 (defvar pdf-annot-inhibit-modification-hooks nil
-  "Non-nil, if running `pdf-annot-modified-functions' should be
-  inhibited after some annotation has changed.")
+  "Controls the behavior of `pdf-annot-modified-functions'.
+
+If non-nil, `pdf-annot-modified-functions' are not run on any
+annotation change.")
 
 (defvar-local pdf-annot-delayed-modified-annotations nil
   "A plist of not yet propagated modifications.
@@ -373,41 +377,43 @@ Setting this after the package was loaded has no effect."
     menu))
 
 (defun pdf-annot-create-color-submenu (a)
+  "Show the user a color menu for their annotation A."
   (let ((menu (make-sparse-keymap)))
     (define-key menu [color-chooser]
-      `(menu-item "Choose ..."
-                  ,(lambda ()
-                     (interactive)
-                     (list-colors-display
-                      nil "*Choose annotation color*"
-                      ;; list-colors-print does not like closures.
-                      (let ((callback (make-symbol "xcallback")))
-                        (fset callback
-                              (lambda (color)
-                                (pdf-annot-put a 'color color)
-                                (setq pdf-annot-color-history
-                                      (cons color
-                                            (remove color pdf-annot-color-history)))
-                                (quit-window t)))
-                        (list 'function callback))))))
+                `(menu-item "Choose ..."
+                            ,(lambda ()
+                               (interactive)
+                               (list-colors-display
+                                nil "*Choose annotation color*"
+                                ;; list-colors-print does not like closures.
+                                (let ((callback (make-symbol "xcallback")))
+                                  (fset callback
+                                        (lambda (color)
+                                          (pdf-annot-put a 'color color)
+                                          (setq pdf-annot-color-history
+                                                (cons color
+                                                      (remove color pdf-annot-color-history)))
+                                          (quit-window t)))
+                                  (list 'function callback))))))
     (dolist (color (butlast (reverse pdf-annot-color-history)
                             (max 0 (- (length pdf-annot-color-history)
                                       12))))
       (define-key menu (vector (intern (format "color-%s" color)))
-        `(menu-item ,color
-                    ,(lambda nil
-                       (interactive)
-                       (pdf-annot-put a 'color color)))))
+                  `(menu-item ,color
+                              ,(lambda nil
+                                 (interactive)
+                                 (pdf-annot-put a 'color color)))))
     menu))
 
 (defun pdf-annot-create-icon-submenu (a)
+  "Show the user an icon menu for the annotation A."
   (let ((menu (make-sparse-keymap)))
     (dolist (icon (reverse pdf-annot-standard-text-icons))
       (define-key menu (vector (intern (format "icon-%s" icon)))
-        `(menu-item ,icon
-                    ,(lambda nil
-                       (interactive)
-                       (pdf-annot-put a 'icon icon)))))
+                  `(menu-item ,icon
+                              ,(lambda nil
+                                 (interactive)
+                                 (pdf-annot-put a 'icon icon)))))
     menu))
 
 ;; * ================================================================== *
@@ -447,6 +453,10 @@ current buffer."
       result)))
 
 (defun pdf-annot-getannot (id &optional buffer)
+  "Return the annotation object for annotation ID.
+
+Optionally take the BUFFER name of the PDF buffer. When none is
+provided, the `current-buffer' is picked up."
   (pdf-annot-create
    (pdf-info-getannot id buffer)
    buffer))
@@ -580,14 +590,19 @@ This function always returns nil."
   nil)
 
 (defun pdf-annot-text-annotation-p (a)
+  "Return non-nil if annotation A is of type text."
   (eq 'text (pdf-annot-get a 'type)))
 
 (defun pdf-annot-markup-annotation-p (a)
+  "Return non-nil if annotation A is a known markup type.
+
+Annotation types are defined in `pdf-annot-markup-annotation-types'."
   (not (null
         (memq (pdf-annot-get a 'type)
               pdf-annot-markup-annotation-types))))
 
 (defun pdf-annot-property-modifiable-p (a property)
+  "Return non-nil if PROPERTY for annotation A is editable."
   (or (memq property '(edges color flags contents))
       (and (pdf-annot-markup-annotation-p a)
            (memq property '(label opacity popup popup-is-open)))
@@ -595,12 +610,18 @@ This function always returns nil."
            (memq property '(icon is-open)))))
 
 (defun pdf-annot-activate-annotation (a)
+  "Run handler functions on A to activate the annotation.
+
+Activation functions are defined in `pdf-annot-activate-handler-functions'."
   (or (run-hook-with-args-until-success
        'pdf-annot-activate-handler-functions
        a)
       (pdf-annot-default-activate-handler a)))
 
 (defun pdf-annot-default-activate-handler (a)
+  "The default activation function to run on annotation A.
+
+Activation functions are defined in `pdf-annot-activate-handler-functions'."
   (cond
    ((pdf-annot-has-attachment-p a)
     (pdf-annot-pop-to-attachment a))
@@ -699,13 +720,13 @@ Signals an error, if A has no data attached."
           (delete-file tmpfile))))))
 
 (defun pdf-annot-attachment-dired (&optional regenerate-p)
-  "List all attachments in a dired buffer.
+  "List all attachments in a Dired buffer.
 
 If REGENERATE-P is non-nil, create attachment's files even if
 they already exist.  Interactively REGENERATE-P is non-nil if a
 prefix argument was given.
 
-Return the dired buffer."
+Return the Dired buffer."
   (interactive (list current-prefix-arg))
   (let ((attachments (pdf-info-getattachments t)))
     (unwind-protect
@@ -900,7 +921,9 @@ i.e. a non mouse-movement event is read."
                          (pdf-annot-getannots page))))
 
 (defun pdf-annot-create-hotspots (a size)
-  "Return a list of image hotspots for annotation A."
+  "Return a list of image hotspots for annotation A.
+
+SIZE is a cons (SX . SY), by which edges are scaled."
   (let ((id (pdf-annot-get-id a))
         (edges (pdf-util-scale
                 (pdf-annot-get-display-edges a)
@@ -922,6 +945,11 @@ i.e. a non mouse-movement event is read."
 
 ;; FIXME: Define a keymap as a template for this. Much cleaner.
 (defun pdf-annot-create-hotspot-binding (id moveable-p annotation)
+  "Create a local keymap for interacting with ANNOTATION using the mouse.
+
+ID is the identifier for the ANNOTATION, as returned
+`pdf-annot-get-id'. MOVEABLE-P indicates whether the annotation
+is moveable."
   ;; Activating
   (local-set-key
    (vector id 'mouse-1)
@@ -986,7 +1014,7 @@ other annotations."
 ;; * ================================================================== *
 
 (defun pdf-annot-add-annotation (type edges &optional property-alist page)
-  "Creates and adds a new annotation of type TYPE to the document.
+  "Create and add a new annotation of type TYPE to the document.
 
 TYPE determines the kind of annotation to add and maybe one of
 `text', `squiggly', `underline', `strike-out' or `highlight'.
@@ -1109,6 +1137,9 @@ Return the new annotation."
         `((color . ,(car pdf-annot-color-history))))))))
 
 (defun pdf-annot-mouse-add-text-annotation (ev)
+  "Add a text annotation using the mouse.
+
+EV describes the captured mouse event."
   (interactive "@e")
   (pdf-annot-add-text-annotation
    (if (eq (car-safe ev)
@@ -1162,7 +1193,9 @@ Return the new annotation."
                                                  &optional color property-alist)
   "Add a new squiggly annotation in the selected window.
 
-See also `pdf-annot-add-markup-annotation'."
+LIST-OF-EDGES defines the annotation boundary. COLOR defines the
+annotation color and PROPERTY-ALIST defines additional annotation
+properties. See also `pdf-annot-add-markup-annotation'."
   (interactive (list (pdf-view-active-region t)))
   (pdf-annot-add-markup-annotation list-of-edges 'squiggly color property-alist))
 
@@ -1170,7 +1203,9 @@ See also `pdf-annot-add-markup-annotation'."
                                                   &optional color property-alist)
   "Add a new underline annotation in the selected window.
 
-See also `pdf-annot-add-markup-annotation'."
+LIST-OF-EDGES defines the annotation boundary. COLOR defines the
+annotation color and PROPERTY-ALIST defines additional annotation
+properties. See also `pdf-annot-add-markup-annotation'."
   (interactive (list (pdf-view-active-region t)))
   (pdf-annot-add-markup-annotation list-of-edges 'underline color property-alist))
 
@@ -1178,7 +1213,9 @@ See also `pdf-annot-add-markup-annotation'."
                                                   &optional color property-alist)
   "Add a new strike-out annotation in the selected window.
 
-See also `pdf-annot-add-markup-annotation'."
+LIST-OF-EDGES defines the annotation boundary. COLOR defines the
+annotation color and PROPERTY-ALIST defines additional annotation
+properties. See also `pdf-annot-add-markup-annotation'."
   (interactive (list (pdf-view-active-region t)))
   (pdf-annot-add-markup-annotation list-of-edges 'strike-out color property-alist))
 
@@ -1186,7 +1223,9 @@ See also `pdf-annot-add-markup-annotation'."
                                                   &optional color property-alist)
   "Add a new highlight annotation in the selected window.
 
-See also `pdf-annot-add-markup-annotation'."
+LIST-OF-EDGES defines the annotation boundary. COLOR defines the
+annotation color and PROPERTY-ALIST defines additional annotation
+properties. See also `pdf-annot-add-markup-annotation'."
   (interactive (list (pdf-view-active-region t)))
   (pdf-annot-add-markup-annotation list-of-edges 'highlight color property-alist))
 
@@ -1387,7 +1426,7 @@ is about to be edited in this buffer.
 
 The default value turns on `latex-mode' if
 `pdf-annot-latex-string-predicate' returns non-nil on the
-annotation's contents and otherwise `text-mode'. "
+annotation's contents and otherwise `text-mode'."
   :type 'function)
 
 (defcustom pdf-annot-edit-contents-display-buffer-action
@@ -1415,8 +1454,15 @@ annotation's contents and otherwise `text-mode'. "
 
 (put 'pdf-annot-edit-contents-minor-mode 'permanent-local t)
 
-;; FIXME: Document pdf-annot-edit-* functions below.
 (defun pdf-annot-edit-contents-finalize (do-save &optional do-kill)
+  "Finalize edit-operations on an Annotation.
+
+If DO-SAVE is t, save the changes to annotation content without
+asking. If DO-SAVE is 'ask, check if the user if contents should
+be saved.
+
+If DO-KILL is t, kill all windows displaying the annotation
+contents. Else just bury the buffers."
   (when (buffer-modified-p)
     (cond
      ((eq do-save 'ask)
@@ -1431,6 +1477,7 @@ annotation's contents and otherwise `text-mode'. "
     (quit-window do-kill win)))
 
 (defun pdf-annot-edit-contents-save-annotation ()
+  "Internal function to save the contents of the annotation under editing."
   (when pdf-annot-edit-contents--annotation
     (pdf-annot-put pdf-annot-edit-contents--annotation
         'contents
@@ -1438,14 +1485,19 @@ annotation's contents and otherwise `text-mode'. "
     (set-buffer-modified-p nil)))
 
 (defun pdf-annot-edit-contents-commit ()
+  "Save the change made to the current annotation."
   (interactive)
   (pdf-annot-edit-contents-finalize t))
 
 (defun pdf-annot-edit-contents-abort ()
+  "Abort the change made to the current annotation."
   (interactive)
   (pdf-annot-edit-contents-finalize nil t))
 
 (defun pdf-annot-edit-contents-noselect (a)
+  "Internal function to setup all prerequisites for editing annotation A.
+
+At any given point of time, only one annotation can be in edit mode."
   (with-current-buffer (pdf-annot-get-buffer a)
     (when (and (buffer-live-p pdf-annot-edit-contents--buffer)
                (not (eq a pdf-annot-edit-contents--annotation)))
@@ -1468,12 +1520,14 @@ annotation's contents and otherwise `text-mode'. "
       (current-buffer))))
 
 (defun pdf-annot-edit-contents (a)
+  "Edit the contents of annotation A."
   (select-window
    (display-buffer
     (pdf-annot-edit-contents-noselect a)
     pdf-annot-edit-contents-display-buffer-action)))
 
 (defun pdf-annot-edit-contents-mouse (ev)
+  "Edit the contents of the annotation described by mouse event EV."
   (interactive "@e")
   (let* ((pos (posn-object-x-y (event-start ev)))
          (a (and pos (pdf-annot-at-position pos))))
@@ -1556,6 +1610,7 @@ belong to the same page and A1 is displayed above/left of A2."
                           (<= e1-left e2-left)))))))))
 
 (defun pdf-annot-list-entries ()
+  "Return all the annotations of this PDF buffer as a `tabulated-list'."
   (unless (buffer-live-p pdf-annot-list-document-buffer)
     (error "No PDF document associated with this buffer"))
   (mapcar #'pdf-annot-list-create-entry
@@ -1564,6 +1619,10 @@ belong to the same page and A1 is displayed above/left of A2."
                 #'pdf-annot-compare-annotations)))
 
 (defun pdf-annot--make-entry-formatter (a)
+  "Return a formatter function for annotation A.
+
+A formatter function takes a format cons-cell and returns
+pretty-printed output."
   (lambda (fmt)
     (let ((entry-type (car fmt))
           (entry-width (cdr fmt))
@@ -1592,7 +1651,7 @@ belong to the same page and A1 is displayed above/left of A2."
                (propertize
                 type 'face
                 `(:background ,color
-                  :foreground ,(funcall contrasty-color color)))
+                              :foreground ,(funcall contrasty-color color)))
              type)))))))
 
 (defun pdf-annot-list-create-entry (a)
@@ -1630,7 +1689,7 @@ belong to the same page and A1 is displayed above/left of A2."
   (tabulated-list-init-header))
 
 (defun pdf-annot-list-annotations ()
-  "List annotations in a dired like buffer.
+  "List annotations in a Dired like buffer.
 
 \\{pdf-annot-list-mode-map}"
   (interactive)
@@ -1663,6 +1722,9 @@ belong to the same page and A1 is displayed above/left of A2."
               #'pdf-annot-list-update nil t)))
 
 (defun pdf-annot-list-goto-annotation (a)
+  "List all the annotations in the current buffer.
+
+Goto the annotation A in the list."
   (with-current-buffer (pdf-annot-get-buffer a)
     (unless (and (buffer-live-p pdf-annot-list-buffer)
                  (get-buffer-window pdf-annot-list-buffer))
@@ -1681,6 +1743,9 @@ belong to the same page and A1 is displayed above/left of A2."
 
 
 (defun pdf-annot-list-update (&optional _fn)
+  "Update the list of annotations on any change.
+
+This is an internal function which runs as a hook in various situations."
   (when (buffer-live-p pdf-annot-list-buffer)
     (with-current-buffer pdf-annot-list-buffer
       (unless tablist-edit-column-minor-mode
@@ -1688,6 +1753,10 @@ belong to the same page and A1 is displayed above/left of A2."
       (tablist-context-window-update))))
 
 (defun pdf-annot-list-context-function (id buffer)
+  "Show the contents of an Annotation.
+
+For an annotation identified by ID, belonging to PDF in BUFFER,
+get the contents and display them on demand."
   (with-current-buffer (get-buffer-create "*Contents*")
     (set-window-buffer nil (current-buffer))
     (let ((inhibit-read-only t))
@@ -1700,6 +1769,12 @@ belong to the same page and A1 is displayed above/left of A2."
       (read-only-mode 1))))
 
 (defun pdf-annot-list-operation-function (op &rest args)
+  "Define bulk operations in Annotation list buffer.
+
+OP is the operation that the user wants to execute. Supported
+operations are `delete' and `find-entry'.
+
+ARGS contain the annotation-ids to operate on."
   (cl-ecase op
     (supported-operations '(delete find-entry))
     (delete
@@ -1735,6 +1810,10 @@ belong to the same page and A1 is displayed above/left of A2."
 (defvar pdf-annot-list-display-annotation--timer nil)
 
 (defun pdf-annot-list-display-annotation-from-id (id)
+  "Display the Annotation ID in the PDF file.
+
+This allows us to follow the tabulated-list of annotations and
+have the PDF buffer automatically move along with us."
   (interactive (list (tabulated-list-get-id)))
   (when id
     (unless (buffer-live-p pdf-annot-list-document-buffer)
@@ -1755,7 +1834,7 @@ belong to the same page and A1 is displayed above/left of A2."
             (pdf-annot-getannot id pdf-annot-list-document-buffer)))))
 
 (define-minor-mode pdf-annot-list-follow-minor-mode
-  ""
+  "Make the PDF follow the annotations in the list buffer."
   :group 'pdf-annot
   (unless (derived-mode-p 'pdf-annot-list-mode)
     (error "Not in pdf-annot-list-mode"))
diff --git a/lisp/pdf-cache.el b/lisp/pdf-cache.el
index 37e79f7..f2cd141 100644
--- a/lisp/pdf-cache.el
+++ b/lisp/pdf-cache.el
@@ -63,6 +63,11 @@ be prefetched and their order."
 (defvar pdf-annot-modified-functions)
 
 (defun pdf-cache--initialize ()
+  "Initialize the cache to store document data.
+
+Note: The cache is only initialized once. After that it needs to
+be cleared before this function makes any changes to it. This is
+an internal function and not meant to be directly used."
   (unless pdf-cache--data
     (setq pdf-cache--data (make-hash-table))
     (add-hook 'pdf-info-close-document-hook #'pdf-cache-clear-data nil t)
@@ -71,6 +76,11 @@ be prefetched and their order."
               nil t)))
 
 (defun pdf-cache--clear-data-of-annotations (fn)
+  "Clear the data cache when annotations are modified.
+
+FN is a closure as described in `pdf-annot-modified-functions'.
+
+Note: This is an internal function and not meant to be directly used."
   (apply #'pdf-cache-clear-data-of-pages
          (mapcar (lambda (a)
                    (cdr (assq 'page a)))
@@ -99,6 +109,7 @@ is nil and VALUE undefined."
       (cons nil nil))))
 
 (defun pdf-cache--data-clear (key &optional page)
+  "Remove KEY from the cache of PAGE."
   (pdf-cache--initialize)
   (puthash page
            (assq-delete-all key (gethash page pdf-cache--data))
@@ -106,11 +117,13 @@ is nil and VALUE undefined."
   nil)
 
 (defun pdf-cache-clear-data-of-pages (&rest pages)
+  "Remove all PAGES from the cache."
   (when pdf-cache--data
     (dolist (page pages)
       (remhash page pdf-cache--data))))
 
 (defun pdf-cache-clear-data ()
+  "Remove the entire cache."
   (interactive)
   (when pdf-cache--data
     (clrhash pdf-cache--data)))
@@ -162,11 +175,22 @@ Make sure, not to modify it's return value." command)))
 (defvar-local pdf-cache--image-cache nil)
 
 (defmacro pdf-cache--make-image (page width data hash)
+  "Make the image that we store in the image cache.
+
+An image is a tuple of PAGE WIDTH DATA HASH."
   `(list ,page ,width ,data ,hash))
-(defmacro pdf-cache--image/page (img) `(nth 0 ,img))
-(defmacro pdf-cache--image/width (img) `(nth 1 ,img))
-(defmacro pdf-cache--image/data (img) `(nth 2 ,img))
-(defmacro pdf-cache--image/hash (img) `(nth 3 ,img))
+(defmacro pdf-cache--image/page (img)
+  "Return the page value for IMG."
+  `(nth 0 ,img))
+(defmacro pdf-cache--image/width (img)
+  "Return the width value for IMG."
+  `(nth 1 ,img))
+(defmacro pdf-cache--image/data (img)
+  "Return the data value for IMG."
+  `(nth 2 ,img))
+(defmacro pdf-cache--image/hash (img)
+  "Return the hash value for IMG."
+  `(nth 3 ,img))
 
 (defun pdf-cache--image-match (image page min-width &optional max-width hash)
   "Match IMAGE with specs.
@@ -190,6 +214,9 @@ hash-value is `eql' to HASH."
 (defun pdf-cache-lookup-image (page min-width &optional max-width hash)
   "Return PAGE's cached PNG data as a string or nil.
 
+Return an image of at least MIN-WIDTH and, if non-nil, maximum
+width MAX-WIDTH and `eql' HASH value.
+
 Does not modify the cache.  See also `pdf-cache-get-image'."
   (let ((image (car (cl-member
                      (list page min-width max-width hash)
@@ -203,7 +230,7 @@ Does not modify the cache.  See also `pdf-cache-get-image'."
   "Return PAGE's PNG data as a string.
 
 Return an image of at least MIN-WIDTH and, if non-nil, maximum
-width MAX-WIDTH and `eql' hash value.
+width MAX-WIDTH and `eql' HASH value.
 
 Remember that image was recently used.
 
@@ -267,12 +294,18 @@ from the cache."
 
 
 (defun pdf-cache--clear-images-of-annotations (fn)
+  "Clear the images cache when annotations are modified.
+
+FN is a closure as described in `pdf-annot-modified-functions'.
+
+Note: This is an internal function and not meant to be directly used."
   (apply #'pdf-cache-clear-images-of-pages
          (mapcar (lambda (a)
                    (cdr (assq 'page a)))
                  (funcall fn t))))
 
 (defun pdf-cache-clear-images-of-pages (&rest pages)
+  "Remove all images of PAGES from the image cache."
   (pdf-cache-clear-images-if
    (lambda (page &rest _) (memq page pages))))
 
@@ -354,6 +387,10 @@ See also `pdf-info-renderpage-highlight' and
     (remove-hook 'pre-command-hook #'pdf-cache--prefetch-stop t))))
 
 (defun pdf-cache-prefetch-pages-function-default ()
+  "The default function to prefetch pages.
+
+See `pdf-cache-prefetch-pages-function' for an explanation of
+what this function does."
   (let ((page (pdf-view-current-page)))
     (pdf-util-remove-duplicates
      (cl-remove-if-not
@@ -382,6 +419,9 @@ See also `pdf-info-renderpage-highlight' and
 
 (defvar pdf-view-use-scaling)
 (defun pdf-cache--prefetch-pages (window image-width)
+  "Internal function to prefetch pages and store them in the cache.
+
+WINDOW and IMAGE-WIDTH decide the page and scale of the final image."
   (when (and (eq window (selected-window))
              (pdf-util-pdf-buffer-p))
     (let ((page (pop pdf-cache--prefetch-pages)))
diff --git a/lisp/pdf-dev.el b/lisp/pdf-dev.el
index 8ac4172..6ea5d8c 100644
--- a/lisp/pdf-dev.el
+++ b/lisp/pdf-dev.el
@@ -31,7 +31,7 @@
     (file-name-directory load-file-name))))
 
 (defun pdf-dev-reload ()
-  "Reload lisp files from source."
+  "Reload Lisp files from source."
   (interactive)
   (let ((default-directory (expand-file-name
                             "lisp"
@@ -53,7 +53,7 @@ Quits the server and sets `pdf-info-epdfinfo-program' to
 Installs a `compilation-finish-functions' which will restart
 epdfinfo after a successful recompilation.
 
-Sets up `load-path' and reloads all PDF Tools lisp files."
+Sets up `load-path' and reloads all PDF Tools Lisp files."
   :group 'pdf-dev
   (let ((lisp-dir (expand-file-name "lisp" pdf-dev-root-directory)))
     (setq load-path (remove lisp-dir load-path))
@@ -71,6 +71,10 @@ Sets up `load-path' and reloads all PDF Tools lisp files."
       (remove-hook 'compilation-finish-functions 'pdf-dev-compilation-finished)))))
 
 (defun pdf-dev-compilation-finished (buffer status)
+  "Restart the epdfinfo server.
+
+BUFFER is the PDF buffer and STATUS is the compilation status of
+building epdfinfo."
   (with-current-buffer buffer
     (when (and (equal status "finished\n")
                (file-equal-p
diff --git a/lisp/pdf-history.el b/lisp/pdf-history.el
index abb9cf2..2d02d68 100644
--- a/lisp/pdf-history.el
+++ b/lisp/pdf-history.el
@@ -110,7 +110,7 @@ represents the current page."
      (1- (length pdf-history-stack))))
 
 (defun pdf-history-backward (n)
-  "Go N-times backward in the history."
+  "Go N times backward in the history."
   (interactive "p")
   (cond
    ((and (> n 0)
@@ -128,7 +128,7 @@ represents the current page."
    (t 0)))
 
 (defun pdf-history-forward (n)
-  "Go N-times forward in the history."
+  "Go N times forward in the history."
   (interactive "p")
   (pdf-history-backward (- n)))
 
diff --git a/lisp/pdf-info.el b/lisp/pdf-info.el
index d3fdaa0..54860f9 100644
--- a/lisp/pdf-info.el
+++ b/lisp/pdf-info.el
@@ -188,7 +188,7 @@ This variable should only be let-bound.")
 (defvar pdf-info--queue t
   "Internally used transmission-queue for the server.
 
-This variable is initially `t', telling the code starting the
+This variable is initially t, telling the code starting the
 server, that it never ran.")
 
 
@@ -307,7 +307,10 @@ error."
 
 (advice-add 'tq-process-buffer :around #'pdf-info--tq-workaround)
 (defun pdf-info--tq-workaround (orig-fun tq &rest args)
-  "Fix a bug in trunk where the wrong callback gets called."
+  "Fix a bug in trunk where the wrong callback gets called.
+
+ORIG-FUN is the callback that should be called. TQ and ARGS are
+the transmission-queue and arguments to the callback."
   ;; FIXME: Make me iterative.
   (if (not (equal (car (process-command (tq-process tq)))
                   pdf-info-epdfinfo-program))
@@ -379,7 +382,7 @@ error."
                  (not (eq (process-status (pdf-info-process))
                           'run))
                  (not (eq cmd 'quit)))
-        (error "The epdfinfo server quit unexpectedly."))
+        (error "The epdfinfo server quit unexpectedly"))
       (cond
        ((null status) response)
        ((eq status 'error)
@@ -387,7 +390,7 @@ error."
        ((eq status 'interrupted)
         (error "epdfinfo: Command was interrupted"))
        (t
-        (error "internal error: invalid response status"))))))
+        (error "Internal error: invalid response status"))))))
 
 (defun pdf-info-interrupt ()
   "FIXME: This command does currently nothing."
@@ -882,7 +885,7 @@ i.e. `pdf-info-asynchronous' is non-nil, transparently.
          (when (and (not ,done)
                     (not (eq (process-status (pdf-info-process))
                              'run)))
-           (error "The epdfinfo server quit unexpectedly."))
+           (error "The epdfinfo server quit unexpectedly"))
          (when ,status
            (error "epdfinfo: %s" ,response))
          ,response))))
diff --git a/lisp/pdf-isearch.el b/lisp/pdf-isearch.el
index 93d7113..4d87a2e 100644
--- a/lisp/pdf-isearch.el
+++ b/lisp/pdf-isearch.el
@@ -128,7 +128,7 @@ keymap is `isearch-mode-map'.")
 (put 'image-scroll-down 'isearch-scroll t)
 
 (define-minor-mode pdf-isearch-active-mode
-  ""
+  "This mode is enabled when isearch is active in a PDF file."
   :group 'pdf-isearch
   (cond
    (pdf-isearch-active-mode
diff --git a/lisp/pdf-tools.el b/lisp/pdf-tools.el
index 660ffad..ff9af5d 100644
--- a/lisp/pdf-tools.el
+++ b/lisp/pdf-tools.el
@@ -73,7 +73,7 @@
 ;;   back to the PDF file.
 ;;
 ;; * Attachments
-;;   Save files attached to the PDF-file or list them in a dired buffer.
+;;   Save files attached to the PDF-file or list them in a Dired buffer.
 ;;
 ;; * Outline
 ;;   Use imenu or a special buffer to examine and navigate the PDF's
@@ -456,7 +456,9 @@ See `pdf-view-mode' and `pdf-tools-enabled-modes'."
         (normal-mode)))))
 
 (defun pdf-tools-pdf-buffer-p (&optional buffer)
-  "Return non-nil if BUFFER contains a PDF document."
+  "Check if the current buffer is a PDF document.
+
+Optionally, take BUFFER as an argument and check if it is a PDF document."
   (save-current-buffer
     (when buffer (set-buffer buffer))
     (save-excursion
@@ -466,10 +468,14 @@ See `pdf-view-mode' and `pdf-tools-enabled-modes'."
         (looking-at "%PDF")))))
 
 (defun pdf-tools-assert-pdf-buffer (&optional buffer)
+  "Throw an error if the current BUFFER does not contain a PDF document."
   (unless (pdf-tools-pdf-buffer-p buffer)
     (error "Buffer does not contain a PDF document")))
 
 (defun pdf-tools-set-modes-enabled (enable &optional modes)
+  "Enable/Disable all the pdf-tools modes on the current buffer based on ENABLE.
+
+Accepts MODES as a optional argument to enable/disable specific modes."
   (dolist (m (or modes pdf-tools-enabled-modes))
     (let ((enabled-p (and (boundp m)
                           (symbol-value m))))
@@ -499,6 +505,7 @@ MODES defaults to `pdf-tools-enabled-modes'."
 
 ;;;###autoload
 (defun pdf-tools-help ()
+  "Show a Help buffer for `pdf-tools'."
   (interactive)
   (help-setup-xref (list #'pdf-tools-help)
                    (called-interactively-p 'interactive))
@@ -521,6 +528,7 @@ MODES defaults to `pdf-tools-enabled-modes'."
   "Non-nil, if debugging PDF Tools.")
 
 (defun pdf-tools-toggle-debug ()
+  "Turn debugging on/off for pdf-tools."
   (interactive)
   (setq pdf-tools-debug (not pdf-tools-debug))
   (when (called-interactively-p 'any)