[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/pdf-tools ca83d66265 3/6: Fix checkdoc errors in pdf-tools
|
From: |
ELPA Syncer |
|
Subject: |
[nongnu] elpa/pdf-tools ca83d66265 3/6: Fix checkdoc errors in pdf-tools lisp code |
|
Date: |
Fri, 31 Dec 2021 00:58:30 -0500 (EST) |
branch: elpa/pdf-tools
commit ca83d662654ca7a2cc0d5f7b826a1163727df916
Author: Vedang Manerikar <ved.manerikar@gmail.com>
Commit: Vedang Manerikar <ved.manerikar@gmail.com>
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
---
lisp/pdf-annot.el | 159 +++++++++++++++++++++++++++++++++++++++-------------
lisp/pdf-cache.el | 50 +++++++++++++++--
lisp/pdf-dev.el | 8 ++-
lisp/pdf-history.el | 4 +-
lisp/pdf-info.el | 13 +++--
lisp/pdf-isearch.el | 2 +-
lisp/pdf-tools.el | 12 +++-
7 files changed, 191 insertions(+), 57 deletions(-)
diff --git a/lisp/pdf-annot.el b/lisp/pdf-annot.el
index 7217622be9..570e589dcc 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 37e79f738a..f2cd1416d4 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 8ac4172415..6ea5d8ca00 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 abb9cf2c84..2d02d685e6 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 d3fdaa0f87..54860f9790 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 93d71133b6..4d87a2e435 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 660ffad628..ff9af5d215 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)
- [nongnu] elpa/pdf-tools updated (a8847b75d3 -> 5b1c367f36), ELPA Syncer, 2021/12/31
- [nongnu] elpa/pdf-tools d866c8749a 1/6: Ignore compilation artifacts, ELPA Syncer, 2021/12/31
- [nongnu] elpa/pdf-tools 69e06e2268 4/6: Clean up and re-organize the README, ELPA Syncer, 2021/12/31
- [nongnu] elpa/pdf-tools 1993c5c3ab 5/6: Add NonGNU ELPA badge to README.org, ELPA Syncer, 2021/12/31
- [nongnu] elpa/pdf-tools ca83d66265 3/6: Fix checkdoc errors in pdf-tools lisp code,
ELPA Syncer <=
- [nongnu] elpa/pdf-tools c5e6be6908 2/6: Indentation and code-quality fixes, ELPA Syncer, 2021/12/31
- [nongnu] elpa/pdf-tools 5b1c367f36 6/6: Clean up NEWS and prepare for a v0.91 release, ELPA Syncer, 2021/12/31