From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 18 Sep 2021 11:56:55 +0000 (+0300)
Subject: Improve doc strings of a recent commit
X-Git-Tag: emacs-28.0.90~865
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=83e3d8d8795c8162490a83f5d1a9d14763b8694f;p=emacs.git

Improve doc strings of a recent commit

* lisp/emacs-lisp/generator.el (iter-defun):
* lisp/emacs-lisp/comp.el (comp-clean-up-stale-eln):
* lisp/emacs-lisp/bytecomp.el (byte-compile-lapcode):
* lisp/emacs-lisp/autoload.el (autoload-insert-section-header):
Include description of arguments in the doc string's first line.
---

diff --git a/lisp/emacs-lisp/autoload.el b/lisp/emacs-lisp/autoload.el
index 38512e04e75..f620cdbb335 100644
--- a/lisp/emacs-lisp/autoload.el
+++ b/lisp/emacs-lisp/autoload.el
@@ -432,8 +432,10 @@ FILE's name."
   file)
 
 (defun autoload-insert-section-header (outbuf autoloads load-name file time)
-  "Insert the section-header line.
-This lists the file name and which functions are in it, etc."
+  "Insert into buffer OUTBUF the section-header line for FILE.
+The header line lists the file name, its \"load name\", its autoloads,
+and the time the FILE was last updated (the time is inserted only
+if `autoload-timestamps' is non-nil, otherwise a fixed fake time is inserted)."
   ;; (cl-assert ;Make sure we don't insert it in the middle of another section.
   ;;  (save-excursion
   ;;    (or (not (re-search-backward
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 8a730618ecd..614aa856f6a 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -915,7 +915,7 @@ CONST2 may be evaluated multiple times."
 				,bytes ,pc))
 
 (defun byte-compile-lapcode (lap)
-  "Turn lapcode into bytecode.  The lapcode is destroyed."
+  "Turn lapcode LAP into bytecode.  The lapcode is destroyed."
   ;; Lapcode modifications: changes the ID of a tag to be the tag's PC.
   (let ((pc 0)			; Program counter
 	op off			; Operation & offset
diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el
index ab36b8aa907..31cae734ccc 100644
--- a/lisp/emacs-lisp/comp.el
+++ b/lisp/emacs-lisp/comp.el
@@ -3804,8 +3804,9 @@ Return the trampoline if found or nil otherwise."
 
 ;;;###autoload
 (defun comp-clean-up-stale-eln (file)
-  "Given FILE remove all its *.eln files in `native-comp-eln-load-path'.
-sharing the original source filename (including FILE)."
+  "Remove all FILE*.eln* files found in `native-comp-eln-load-path'.
+The files to be removed are those produced from the original source
+filename (including FILE)."
   (when (string-match (rx "-" (group-n 1 (1+ hex)) "-" (1+ hex) ".eln" eos)
                       file)
     (cl-loop
diff --git a/lisp/emacs-lisp/generator.el b/lisp/emacs-lisp/generator.el
index 7801fc90706..2075ac472d1 100644
--- a/lisp/emacs-lisp/generator.el
+++ b/lisp/emacs-lisp/generator.el
@@ -668,7 +668,7 @@ sub-iterator function returns via `iter-end-of-sequence'."
          (iter-close ,valsym)))))
 
 (defmacro iter-defun (name arglist &rest body)
-  "Create a generator NAME.
+  "Create a generator NAME that accepts ARGLIST as its arguments.
 When called as a function, NAME returns an iterator value that
 encapsulates the state of a computation that produces a sequence
 of values.  Callers can retrieve each value using `iter-next'."