master c4e8d1d: Improve some doc strings in bookmark.el

[Karl Fogel]

branch: master
commit c4e8d1dbe2e79824c8696b4c7adc510ac4e5515e
Author: Karl Fogel <kfogel@red-bean.com>
Commit: Karl Fogel <kfogel@red-bean.com>

    Improve some doc strings in bookmark.el
    
    * lisp/bookmark.el (bookmark-bmenu-load): Describe prefix argument
      behavior.  Refer to related functions for more information.
      (bookmark-bmenu-save): Likewise refer to related functions.
    
    As discussed in this thread:
    
      https://lists.gnu.org/archive/html/emacs-devel/2021-05/msg00389.html
    
      From: Karl Fogel
      To: Eli Zaretskii
      Cc: Matthias Meulien, Drew Adams, Lars Ingebrigtsen,
          Stefan Monnier, Emacs Devel
      Subject: Re: [External] : Re: [PATCH] When deleting in bookmark menu,
               prompt for confirmation.
      Date: Sun, 09 May 2021 13:37:52 -0500
      Message-ID: <87h7jboirj.fsf@red-bean.com>
---
 lisp/bookmark.el | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 64b467a..31e41a9 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -2054,7 +2054,10 @@ You can mark bookmarks with the 
\\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-mar
 
 (defun bookmark-bmenu-save ()
   "Save the current list into a bookmark file.
-With a prefix arg, prompts for a file to save them in."
+With a prefix arg, prompts for a file to save them in.
+
+See also the related behaviors of `bookmark-load' and
+`bookmark-bmenu-load'."
   (interactive nil bookmark-bmenu-mode)
   (save-excursion
     (save-window-excursion
@@ -2063,7 +2066,19 @@ With a prefix arg, prompts for a file to save them in."
 
 
 (defun bookmark-bmenu-load ()
-  "Load the bookmark file and rebuild the bookmark menu-buffer."
+  "Load bookmarks from a file and rebuild the bookmark menu-buffer.
+Prompt for a file, with the default choice being the value of
+`bookmark-default-file'.
+
+With a prefix argument, replace the current ambient bookmarks
+(i.e., the ones in `bookmark-alist') with the ones from the selected
+file and make that file be the new value of `bookmark-default-file'.
+In other words, a prefix argument means \"switch over to the bookmark
+universe defined in the loaded file\".  Without a prefix argument,
+just add the loaded bookmarks into the current ambient set.
+
+See the documentation for `bookmark-load' for more details; see also
+the related behaviors of `bookmark-save' and `bookmark-bmenu-save'."
   (interactive nil bookmark-bmenu-mode)
   (bookmark-bmenu-ensure-position)
   (save-excursion