Subject: bug#35916: closed (Re: bug#35916: [PATCH] checkdoc fixes in bookmark.el)

From: [email-masked] (GNU bug Tracking System)
Date: Sun, 09 Jun 2019 06:52:02 +0000

Your bug report

#35916: [PATCH] checkdoc fixes in bookmark.el

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
35916: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=35916
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#35916: [PATCH] checkdoc fixes in bookmark.el
From: Eli Zaretskii <[email-masked]>
To: Stefan Kangas <[email-masked]>
Cc: [email-masked]
Date: Sun, 09 Jun 2019 09:51:36 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Stefan Kangas <[email-masked]>
> Date: Sat, 8 Jun 2019 19:22:38 +0200
> Cc: [email-masked]
> 
> Eli Zaretskii <[email-masked]> writes:
> > The first line of the doc string should mention the arguments, in this
> > case EVENT.  Could you please rework this hunk and resubmit the patch?
> 
> Sure.  I've attached a patch with the following fix:

Thanks, pushed to the master branch.

Subject: [PATCH] checkdoc fixes in bookmark.el
From: Stefan Kangas <[email-masked]>
To: [email-masked]
Date: Sun, 26 May 2019 12:59:11 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

I ran checkdoc on bookmark.el and fixed some of the errors.
Please see attached patch.

Thanks,
Stefan Kangas
From d46eef6146310c700cd04f499119c164f5461391 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
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-alist)
(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 | 40 ++++++++++++++++++++++------------------
 1 file changed, 22 insertions(+), 18 deletions(-)

diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index b1fe690dac..ef03023965 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)
@@ -260,7 +261,7 @@ bookmark-alist
  ANNOTATION is a string that describes the bookmark.
    See options `bookmark-use-annotations' and
    `bookmark-automatically-show-annotations'.
- HANDLER is a function that provides the bookmark-jump behavior for a
+ HANDLER is a function that provides the `bookmark-jump' behavior for a
  specific kind of bookmark.  This is the case for Info bookmarks,
  for instance.  HANDLER must accept a bookmark as its single argument.")
 
@@ -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 exists, 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 file path 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