From 5deabc350a553a41e379399335aeeacb8bb6628b Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sun, 26 May 2019 12:48:26 +0200 Subject: [PATCH] Checkdoc fixes in bookmark.el * bookmark.el (bookmark-bmenu-inline-header-height) (bookmark-bmenu-marks-width, bookmark-map, bookmark-quit-flag) (bookmark-name-from-full-record, bookmark-set-internal) (bookmark-insert-annotation, bookmark--jump-via) (bookmark-bmenu-set-header, bookmark-show-annotation) (bookmark-bmenu-other-window-with-mouse, bookmark-bmenu-relocate): Checkdoc docstring fixes. --- lisp/bookmark.el | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/lisp/bookmark.el b/lisp/bookmark.el index b1fe690dac..c3899bcfc0 100644 --- a/lisp/bookmark.el +++ b/lisp/bookmark.el @@ -136,12 +136,13 @@ bookmark-bmenu-use-header-line :group 'bookmark) (defconst bookmark-bmenu-inline-header-height 2 - "Number of lines used for the *Bookmark List* header -\(only significant when `bookmark-bmenu-use-header-line' is nil).") + "Number of lines used for the *Bookmark List* header. +\(This is only significant when `bookmark-bmenu-use-header-line' +is nil.)") (defconst bookmark-bmenu-marks-width 2 - "Number of columns (chars) used for the *Bookmark List* marks column, -including the annotations column.") + "Number of columns (chars) used for the *Bookmark List* marks column. +This includes the annotations column.") (defcustom bookmark-bmenu-file-column 30 "Column at which to display filenames in a buffer listing bookmarks. @@ -221,7 +222,7 @@ bookmark-map "Keymap containing bindings to bookmark functions. It is not bound to any key by default: to bind it so that you have a bookmark prefix, just use `global-set-key' and bind a -key of your choice to `bookmark-map'. All interactive bookmark +key of your choice to variable `bookmark-map'. All interactive bookmark functions have a binding in this keymap.") ;;;###autoload (fset 'bookmark-map bookmark-map) @@ -301,7 +302,7 @@ bookmark-yank-point (defvar bookmark-quit-flag nil - "Non nil make `bookmark-bmenu-search' quit immediately.") + "Non-nil means `bookmark-bmenu-search' quits immediately.") ;; Helper functions and macros. @@ -318,8 +319,8 @@ with-buffer-modified-unmodified ;; Everyone else should go through them. (defun bookmark-name-from-full-record (bookmark-record) - "Return the name of BOOKMARK-RECORD. BOOKMARK-RECORD is, e.g., -one element from `bookmark-alist'." + "Return the name of BOOKMARK-RECORD. +BOOKMARK-RECORD is, e.g., one element from `bookmark-alist'." (car bookmark-record)) @@ -811,7 +812,7 @@ bookmark-set-internal (cond ((eq overwrite-or-push nil) (if (bookmark-get-bookmark str t) - (error "A bookmark named \"%s\" already exists." str) + (error "A bookmark named \"%s\" already exists" str) (bookmark-store str (cdr record) nil))) ((eq overwrite-or-push 'overwrite) (bookmark-store str (cdr record) nil)) @@ -936,6 +937,7 @@ bookmark-edit-annotation-mode-map "Keymap for editing an annotation of a bookmark.") (defun bookmark-insert-annotation (bookmark-name-or-record) + "Insert annotation for BOOKMARK-NAME-OR-RECORD at point." (insert (funcall bookmark-edit-annotation-text-func bookmark-name-or-record)) (let ((annotation (bookmark-get-annotation bookmark-name-or-record))) (if (and annotation (not (string-equal annotation ""))) @@ -1065,8 +1067,8 @@ bookmark-after-jump-hook Useful for example to unhide text in `outline-mode'.") (defun bookmark--jump-via (bookmark-name-or-record display-function) - "Handle BOOKMARK-NAME-OR-RECORD, then call DISPLAY-FUNCTION with -current buffer as argument. + "Handle BOOKMARK-NAME-OR-RECORD, then call DISPLAY-FUNCTION. +DISPLAY-FUNCTION is called with the current buffer as argument. After calling DISPLAY-FUNCTION, set window point to the point specified by BOOKMARK-NAME-OR-RECORD, if necessary, run `bookmark-after-jump-hook', @@ -1675,7 +1677,7 @@ 'list-bookmarks (defalias 'edit-bookmarks 'bookmark-bmenu-list) (defun bookmark-bmenu-set-header () - "Sets the immutable header line." + "Set the immutable header line." (let ((header (concat "%% " "Bookmark"))) (when bookmark-bmenu-toggle-filenames (setq header (concat header @@ -1835,8 +1837,8 @@ bookmark-bmenu-bookmark (defun bookmark-show-annotation (bookmark-name-or-record) - "Display the annotation for BOOKMARK-NAME-OR-RECORD in a buffer, -if an annotation exists." + "Display the annotation for BOOKMARK-NAME-OR-RECORD in a buffer. +If the annotation does not exist, do nothing." (let ((annotation (bookmark-get-annotation bookmark-name-or-record))) (when (and annotation (not (string-equal annotation ""))) (save-excursion @@ -1997,7 +1999,9 @@ bookmark-bmenu-switch-other-window (bookmark--jump-via bookmark fun))) (defun bookmark-bmenu-other-window-with-mouse (event) - "Select bookmark at the mouse pointer in other window, leaving bookmark menu visible." + "Select bookmark at the mouse pointer in other window. +Move point to the position of EVENT, and leave bookmark menu +visible." (interactive "e") (with-current-buffer (window-buffer (posn-window (event-end event))) (save-excursion @@ -2123,8 +2127,8 @@ bookmark-bmenu-locate (message "%s" (bookmark-location bmrk)))) (defun bookmark-bmenu-relocate () - "Change the file path of the bookmark on the current line, - prompting with completion for the new path." + "Change the absolute file name of the bookmark on the current line. +Prompt with completion for the new path." (interactive) (let ((bmrk (bookmark-bmenu-bookmark)) (thispoint (point))) -- 2.11.0