Document bookmark annotations in Emacs Manual (bug#36417)

* doc/emacs/regs.texi (Bookmarks): Document annotations.
* lisp/bookmark.el (bookmark-use-annotations): Clarify docstring.

2 files changed, 8 insertions, 4 deletions

diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index 37026946477..68a8245b34d 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -359,6 +359,13 @@ saves bookmarks if you explicitly use @kbd{M-x bookmark-save}.
   The variable @code{bookmark-default-file} specifies the file in
 which to save bookmarks by default.
 
+@vindex bookmark-use-annotations
+@cindex bookmark annotations
+  If you set the variable @code{bookmark-use-annotations} to @code{t},
+setting a bookmark will query for an annotation.  If a bookmark has an
+annotation, it is automatically shown in a separate window when you
+jump to the bookmark.
+
 @vindex bookmark-search-size
   Bookmark position values are saved with surrounding context, so that
 @code{bookmark-jump} can find the proper position even if the file is
diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 9a3a2a3bdf8..bbef0a927dc 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -36,9 +36,6 @@
 
 ;;; Misc comments:
 ;;
-;; If variable bookmark-use-annotations is non-nil, an annotation is
-;; queried for when setting a bookmark.
-;;
 ;; The bookmark list is sorted lexically by default, but you can turn
 ;; this off by setting bookmark-sort-flag to nil.  If it is nil, then
 ;; the list will be presented in the order it is recorded
@@ -52,7 +49,7 @@
 
 
 (defcustom bookmark-use-annotations nil
-  "If non-nil, saving a bookmark queries for an annotation in a buffer."
+  "If non-nil, setting a bookmark queries for an annotation in a buffer."
   :type 'boolean
   :group 'bookmark)