; Improve doc strings in register.el

* lisp/register.el (register-preview-delay)
(register-describe-oneline, register-preview-default)
(register-preview-function, register-preview, point-to-register)
(window-configuration-to-register)
(frame-configuration-to-register, jump-to-register)
(register-val-jump-to, number-to-register, increment-register)
(view-register, list-registers, register-val-describe)
(insert-register, register-val-insert, copy-to-register)
(append-to-register, prepend-to-register)
(copy-rectangle-to-register): Doc fixes.

lisp/register.el

@@ -92,7 +92,7 @@ of the marked text."
 		 (character :tag "Use register" :value ?+)))
 
 (defcustom register-preview-delay 1
-  "If non-nil, time to wait in seconds before popping up a preview window.
+  "If non-nil, time to wait in seconds before popping up register preview window.
 If nil, do not show register previews, unless `help-char' (or a member of
 `help-event-list') is pressed."
   :version "24.4"
@@ -109,7 +109,7 @@ See the documentation of the variable `register-alist' for possible VALUEs."
   (setf (alist-get register register-alist) value))
 
 (defun register-describe-oneline (c)
-  "One-line description of register C."
+  "Return a one-line description of register C."
   (let ((d (replace-regexp-in-string
             "\n[ \t]*" " "
             (with-output-to-string (describe-register-1 c)))))
@@ -118,19 +118,19 @@ See the documentation of the variable `register-alist' for possible VALUEs."
       d)))
 
 (defun register-preview-default (r)
-  "Default function for the variable `register-preview-function'."
+  "Function that is the default value of the variable `register-preview-function'."
   (format "%s: %s\n"
 	  (single-key-description (car r))
 	  (register-describe-oneline (car r))))
 
 (defvar register-preview-function #'register-preview-default
   "Function to format a register for previewing.
-Takes one argument, a cons (NAME . CONTENTS) as found in `register-alist'.
+Called with one argument, a cons (NAME . CONTENTS) as found in `register-alist'.
-Returns a string.")
+The function should return a string, the description of teh argument.")
 
 (defun register-preview (buffer &optional show-empty)
-  "Pop up a window to show register preview in BUFFER.
+  "Pop up a window showing the registers preview in BUFFER.
-If SHOW-EMPTY is non-nil show the window even if no registers.
+If SHOW-EMPTY is non-nil, show the window even if no registers.
 Format of each entry is controlled by the variable `register-preview-function'."
   (when (or show-empty (consp register-alist))
     (with-current-buffer-window
@@ -180,12 +180,12 @@ display such a window regardless."
       (and (get-buffer buffer) (kill-buffer buffer)))))
 
 (defun point-to-register (register &optional arg)
-  "Store current location of point in register REGISTER.
+  "Store current location of point in REGISTER.
-With prefix argument, store current frame configuration (a.k.a. \"frameset\").
+With prefix argument ARG, store current frame configuration (a.k.a. \"frameset\").
 Use \\[jump-to-register] to go to that location or restore that configuration.
-Argument is a character, naming the register.
+Argument is a character, the name of the register.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (list (register-read-with-preview
                       (if current-prefix-arg
                           "Frame configuration to register: "
@@ -198,11 +198,11 @@ Interactively, reads the register using `register-read-with-preview'."
 		  (point-marker))))
 
 (defun window-configuration-to-register (register &optional _arg)
-  "Store the window configuration of the selected frame in register REGISTER.
+  "Store the window configuration of the selected frame in REGISTER.
 Use \\[jump-to-register] to restore the configuration.
-Argument is a character, naming the register.
+Argument is a character, the name of the register.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (list (register-read-with-preview
 		      "Window configuration to register: ")
 		     current-prefix-arg))
@@ -215,12 +215,12 @@ Interactively, reads the register using `register-read-with-preview'."
 				   '(register) "24.4")
 
 (defun frame-configuration-to-register (register &optional _arg)
-  "Store the window configuration of all frames in register REGISTER.
+  "Store the window configurations of all frames in REGISTER.
 \(This window configuration is also known as \"frameset\").
 Use \\[jump-to-register] to restore the configuration.
-Argument is a character, naming the register.
+Argument is a character, the name of the register.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (list (register-read-with-preview
 		      "Frame configuration to register: ")
 		     current-prefix-arg))
@@ -236,19 +236,21 @@ Interactively, reads the register using `register-read-with-preview'."
 
 (defalias 'register-to-point 'jump-to-register)
 (defun jump-to-register (register &optional delete)
-  "Move point to location stored in a register.
+  "Go to location stored in REGISTER, or restore configuration stored there.
-Push the mark if jumping moves point, unless called in succession.
+Push the mark if going to the location moves point, unless called in succession.
 If the register contains a file name, find that file.
-\(To put a file name in a register, you must use `set-register'.)
+If the register contains a buffer name, switch to that buffer.
+\(To put a file or buffer name in a register, you must use `set-register'.)
 If the register contains a window configuration (one frame) or a frameset
-\(all frames), restore that frame or all frames accordingly.
+\(all frames), restore the configuration of that frame or of all frames
-First argument is a character, naming the register.
+accordingly.
+First argument REGISTER is a character, the name of the register.
 Optional second arg DELETE non-nil (interactively, prefix argument) says
 to delete any existing frames that the frameset doesn't mention.
 \(Otherwise, these frames are iconified.)  This argument is currently
 ignored if the register contains anything but a frameset.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (list (register-read-with-preview "Jump to register: ")
 		     current-prefix-arg))
   (let ((val (get-register register)))
@@ -256,6 +258,7 @@ Interactively, reads the register using `register-read-with-preview'."
 
 (cl-defgeneric register-val-jump-to (_val _arg)
   "Execute the \"jump\" operation of VAL.
+VAL is the contents of a register as returned by `get-register'.
 ARG is the value of the prefix argument or nil."
   (user-error "Register doesn't contain a buffer position or configuration"))
 
@@ -305,13 +308,13 @@ ARG is the value of the prefix argument or nil."
 			    (marker-position (cdr elem))))))))
 
 (defun number-to-register (number register)
-  "Store a number in a register.
+  "Store NUMBER in REGISTER.
-Two args, NUMBER and REGISTER (a character, naming the register).
+REGISTER is a character, the name of the register.
-If NUMBER is nil, a decimal number is read from the buffer starting
+If NUMBER is nil, a decimal number is read from the buffer
 at point, and point moves to the end of that number.
 Interactively, NUMBER is the prefix arg (none means nil).
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (list current-prefix-arg
 		     (register-read-with-preview "Number to register: ")))
   (set-register register
@@ -324,8 +327,8 @@ Interactively, reads the register using `register-read-with-preview'."
 		    0))))
 
 (defun increment-register (prefix register)
-  "Augment contents of REGISTER.
+  "Augment contents of REGISTER using PREFIX.
-Interactively, PREFIX is in raw form.
+Interactively, PREFIX is the raw prefix argument.
 
 If REGISTER contains a number, add `prefix-numeric-value' of
 PREFIX to it.
@@ -333,7 +336,7 @@ PREFIX to it.
 If REGISTER is empty or if it contains text, call
 `append-to-register' with `delete-flag' set to PREFIX.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (list current-prefix-arg
 		     (register-read-with-preview "Increment register: ")))
   (let ((register-val (get-register register)))
@@ -346,10 +349,10 @@ Interactively, reads the register using `register-read-with-preview'."
      (t (user-error "Register does not contain a number or text")))))
 
 (defun view-register (register)
-  "Display what is contained in register named REGISTER.
+  "Display the description of the contents of REGISTER.
-The Lisp value REGISTER is a character.
+REGISTER is a character, the name of the register.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (list (register-read-with-preview "View register: ")))
   (let ((val (get-register register)))
     (if (null val)
@@ -358,7 +361,7 @@ Interactively, reads the register using `register-read-with-preview'."
 	(describe-register-1 register t)))))
 
 (defun list-registers ()
-  "Display a list of nonempty registers saying briefly what they contain."
+  "Display the list of nonempty registers with brief descriptions of contents."
   (interactive)
   (let ((list (copy-sequence register-alist)))
     (setq list (sort list (lambda (a b) (< (car a) (car b)))))
@@ -376,7 +379,10 @@ Interactively, reads the register using `register-read-with-preview'."
     (register-val-describe val verbose)))
 
 (cl-defgeneric register-val-describe (val verbose)
-  "Print description of register value VAL to `standard-output'."
+  "Print description of register value VAL to `standard-output'.
+Second argument VERBOSE is ignored, unless VAL is not one of the
+supported kinds of register contents, in which case it is displayed
+using `prin1'."
   (princ "Garbage:\n")
   (if verbose (prin1 val)))
 
@@ -471,13 +477,14 @@ Interactively, reads the register using `register-read-with-preview'."
       (princ "the empty string")))))
 
 (defun insert-register (register &optional arg)
-  "Insert contents of register REGISTER.  (REGISTER is a character.)
+  "Insert contents of REGISTER at point.
-Normally puts point before and mark after the inserted text.
+REGISTER is a character, the name of the register.
-If optional second arg is non-nil, puts mark before and point after.
+Normally puts point before and mark after the inserted text, but
-Interactively, second arg is nil if prefix arg is supplied and t
+if optional second argument ARG is non-nil, puts mark before and
-otherwise.
+point after.  Interactively, ARG is nil if prefix arg is supplied,
+and t otherwise.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'."
   (interactive (progn
 		 (barf-if-buffer-read-only)
 		 (list (register-read-with-preview "Insert register: ")
@@ -488,7 +495,7 @@ Interactively, reads the register using `register-read-with-preview'."
   (if (not arg) (exchange-point-and-mark)))
 
 (cl-defgeneric register-val-insert (_val)
-  "Insert register value VAL."
+  "Insert register value VAL in current buffer at point."
   (user-error "Register does not contain text"))
 
 (cl-defmethod register-val-insert ((val registerv))
@@ -511,14 +518,17 @@ Interactively, reads the register using `register-read-with-preview'."
     (cl-call-next-method val)))
 
 (defun copy-to-register (register start end &optional delete-flag region)
-  "Copy region into register REGISTER.
+  "Copy region of text between START and END into REGISTER.
-With prefix arg, delete as well.
+If DELETE-FLAG is non-nil (interactively, prefix arg), delete the region
-Called from program, takes five args: REGISTER, START, END, DELETE-FLAG,
+after copying.
+Called from Lisp, takes five args: REGISTER, START, END, DELETE-FLAG,
 and REGION.  START and END are buffer positions indicating what to copy.
-The optional argument REGION if non-nil, indicates that we're not just
+The optional argument REGION, if non-nil, means START..END denotes the
-copying some text between START and END, but we're copying the region.
+region.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview'
+and use mark and point as START and END; REGION is always non-nil in
+this case."
   (interactive (list (register-read-with-preview "Copy to register: ")
 		     (region-beginning)
 		     (region-end)
@@ -534,12 +544,14 @@ Interactively, reads the register using `register-read-with-preview'."
 	 (indicate-copied-region))))
 
 (defun append-to-register (register start end &optional delete-flag)
-  "Append region to text in register REGISTER.
+  "Append region of text between START and END to REGISTER.
-With prefix arg, delete as well.
+If DELETE-FLAG is non-nil (interactively, prefix arg), delete the region
-Called from program, takes four args: REGISTER, START, END and DELETE-FLAG.
+after appending.
+Called from Lisp, takes four args: REGISTER, START, END and DELETE-FLAG.
 START and END are buffer positions indicating what to append.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview',
+and use mark and point as START and END."
   (interactive (list (register-read-with-preview "Append to register: ")
 		     (region-beginning)
 		     (region-end)
@@ -558,12 +570,14 @@ Interactively, reads the register using `register-read-with-preview'."
 	 (indicate-copied-region))))
 
 (defun prepend-to-register (register start end &optional delete-flag)
-  "Prepend region to text in register REGISTER.
+  "Prepend region of text between START and END to REGISTER.
-With prefix arg, delete as well.
+If DELETE-FLAG is non-nil (interactively, prefix arg), delete the region
+after prepending.
 Called from program, takes four args: REGISTER, START, END and DELETE-FLAG.
 START and END are buffer positions indicating what to prepend.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview',
+and use mark and point as START and END."
   (interactive (list (register-read-with-preview "Prepend to register: ")
 		     (region-beginning)
 		     (region-end)
@@ -582,14 +596,16 @@ Interactively, reads the register using `register-read-with-preview'."
 	 (indicate-copied-region))))
 
 (defun copy-rectangle-to-register (register start end &optional delete-flag)
-  "Copy rectangular region into register REGISTER.
+  "Copy rectangular region of text between START and END into REGISTER.
-With prefix arg, delete as well.
+If DELETE-FLAG is non-nil (interactively, prefix arg), delete the region
-To insert this register in the buffer, use \\[insert-register].
+after copying.
+To insert this register into a buffer, use \\[insert-register].
 
-Called from a program, takes four args: REGISTER, START, END and DELETE-FLAG.
+Called from Lisp, takes four args: REGISTER, START, END and DELETE-FLAG.
 START and END are buffer positions giving two corners of rectangle.
 
-Interactively, reads the register using `register-read-with-preview'."
+Interactively, prompt for REGISTER using `register-read-with-preview',
+and use mark and point as START and END."
   (interactive (list (register-read-with-preview
 		      "Copy rectangle to register: ")
 		     (region-beginning)