[Emacs-diffs] master f4eeb0f: * lisp/subr.el (dotimes): Deprecate RESULT field. (Bug#16206)

[Juri Linkov]

branch: master
commit f4eeb0f5ae448db0f064f6305ab0bc0c3bae071a
Author: Juri Linkov <address@hidden>
Commit: Juri Linkov <address@hidden>

    * lisp/subr.el (dotimes): Deprecate RESULT field.  (Bug#16206)
    
    * doc/lispref/control.texi (Iteration):
    * doc/misc/cl.texi (Iteration): Document deprecation of its use.
    * doc/lispintro/emacs-lisp-intro.texi (dotimes):
    * test/src/emacs-module-tests.el (multiply-string):
    * test/lisp/filenotify-tests.el (file-notify-test07-many-events):
    Place RESULT field after the form.
---
 doc/lispintro/emacs-lisp-intro.texi | 21 +++++++++++----------
 doc/lispref/control.texi            |  3 ++-
 doc/misc/cl.texi                    |  4 ++--
 lisp/subr.el                        |  2 +-
 test/lisp/filenotify-tests.el       | 10 ++++++----
 test/src/emacs-module-tests.el      |  5 +++--
 6 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi 
b/doc/lispintro/emacs-lisp-intro.texi
index b672d7c..4d514aa 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -11013,9 +11013,8 @@ The @code{dotimes} macro is similar to @code{dolist}, 
except that it
 loops a specific number of times.
 
 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
-and so forth each time around the loop, and the value of the third
-argument is returned.  You need to provide the value of the second
-argument, which is how many times the macro loops.
+and so forth each time around the loop.  You need to provide the value
+of the second argument, which is how many times the macro loops.
 
 @need 1250
 For example, the following binds the numbers from 0 up to, but not
@@ -11027,17 +11026,18 @@ three numbers in all, starting with zero as the first 
number.)
 @smallexample
 @group
 (let (value)      ; otherwise a value is a void variable
-  (dotimes (number 3 value)
-    (setq value (cons number value))))
+  (dotimes (number 3)
+    (setq value (cons number value)))
+  value)
 
 @result{} (2 1 0)
 @end group
 @end smallexample
 
 @noindent
address@hidden returns @code{value}, so the way to use
address@hidden is to operate on some expression @var{number} number of
-times and then return the result, either as a list or an atom.
+The way to use @code{dotimes} is to operate on some expression
address@hidden number of times and then return the result, either as
+a list or an atom.
 
 @need 1250
 Here is an example of a @code{defun} that uses @code{dotimes} to add
@@ -11048,8 +11048,9 @@ up the number of pebbles in a triangle.
 (defun triangle-using-dotimes (number-of-rows)
   "Using `dotimes', add up the number of pebbles in a triangle."
 (let ((total 0))  ; otherwise a total is a void variable
-  (dotimes (number number-of-rows total)
-    (setq total (+ total (1+ number))))))
+  (dotimes (number number-of-rows)
+    (setq total (+ total (1+ number))))
+  total))
 
 (triangle-using-dotimes 4)
 @end group
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index adec632..42aa3c9 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -703,7 +703,8 @@ This construct executes @var{body} once for each integer 
from 0
 (inclusive) to @var{count} (exclusive), binding the variable @var{var}
 to the integer for the current iteration.  Then it returns the value
 of evaluating @var{result}, or @code{nil} if @var{result} is omitted.
-Here is an example of using @code{dotimes} to do something 100 times:
+Use of @var{result} is deprecated.  Here is an example of using
address@hidden to do something 100 times:
 
 @example
 (dotimes (i 100)
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index bf85b00..5ae0faf 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1712,9 +1712,9 @@ but surrounds the loop with an implicit @code{nil} block.
 The body is executed with @var{var} bound to the integers
 from zero (inclusive) to @var{count} (exclusive), in turn.  Then
 @c FIXME lispref does not state this part explicitly, could move this there.
-the @code{result} form is evaluated with @var{var} bound to the total
+the @var{result} form is evaluated with @var{var} bound to the total
 number of iterations that were done (i.e., @code{(max 0 @var{count})})
-to get the return value for the loop form.
+to get the return value for the loop form.  Use of @var{result} is deprecated.
 @end defmac
 
 @defmac cl-do-symbols (var [obarray [result]]) address@hidden
diff --git a/lisp/subr.el b/lisp/subr.el
index dd51539..9f6cade 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -223,7 +223,7 @@ Then evaluate RESULT to get return value, default nil.
   "Loop a certain number of times.
 Evaluate BODY with VAR bound to successive integers running from 0,
 inclusive, to COUNT, exclusive.  Then evaluate RESULT to get
-the return value (nil if RESULT is omitted).
+the return value (nil if RESULT is omitted).  Its use is deprecated.
 
 \(fn (VAR COUNT [RESULT]) BODY...)"
   (declare (indent 1) (debug dolist))
diff --git a/test/lisp/filenotify-tests.el b/test/lisp/filenotify-tests.el
index 219fa74..56403f4 100644
--- a/test/lisp/filenotify-tests.el
+++ b/test/lisp/filenotify-tests.el
@@ -1129,14 +1129,16 @@ delivered."
             ;; w32notify fires both `deleted' and `renamed' events.
             ((string-equal (file-notify--test-library) "w32notify")
              (let (r)
-               (dotimes (_i n r)
-                 (setq r (append '(deleted renamed) r)))))
+               (dotimes (_i n)
+                 (setq r (append '(deleted renamed) r)))
+               r))
             ;; cygwin fires `changed' and `deleted' events, sometimes
             ;; in random order.
             ((eq system-type 'cygwin)
              (let (r)
-               (dotimes (_i n (cons :random r))
-                 (setq r (append '(changed deleted) r)))))
+               (dotimes (_i n)
+                 (setq r (append '(changed deleted) r)))
+               (cons :random r)))
             (t (make-list n 'renamed)))
           (let ((source-file-list source-file-list)
                 (target-file-list target-file-list))
diff --git a/test/src/emacs-module-tests.el b/test/src/emacs-module-tests.el
index 8b6328d..9ef5a47 100644
--- a/test/src/emacs-module-tests.el
+++ b/test/src/emacs-module-tests.el
@@ -138,8 +138,9 @@ changes."
 
 (defun multiply-string (s n)
   (let ((res ""))
-    (dotimes (i n res)
-      (setq res (concat res s)))))
+    (dotimes (i n)
+      (setq res (concat res s)))
+    res))
 
 (ert-deftest mod-test-globref-make-test ()
   (let ((mod-str (mod-test-globref-make))