bug#16206: 24.3; Incorrect unused variable byte-compiler warning in dotimes

[Juri Linkov]

>>   (let ((count 10))
>>     (dotimes (i count count) (print i)))
>
> I don't disagree with you: I think this 3rd field is a misfeature
> of dotimes.  But IIRC there is code out there which uses it.

And I agree with you that the 3rd field is a misfeature -
in more modern Lisp languages like Clojure there is no 3rd field.

But there is the need to unlearn it - to update the documentation
and examples:

diff --git a/lisp/subr.el b/lisp/subr.el
index 9cf7d59..379cf33 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -223,7 +223,8 @@ dotimes
   "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).  Note that RESULT
+should not be used unless it makes use of VAR.
 
 \(fn (VAR COUNT [RESULT]) BODY...)"
   (declare (indent 1) (debug dolist))
diff --git a/etc/NEWS b/etc/NEWS
index bde9b89..06896d4 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -433,6 +433,9 @@ names" in the Tramp manual for full documentation of these 
facilities.
 
 * Incompatible Lisp Changes in Emacs 27.1
 
+** The RESULT argument of ‘dotimes’ should not be used
+unless it makes use of the VAR argument.
+
 ** The 'repetitions' argument of 'benchmark-run' can now also be a variable.
 ** The FILENAME argument to 'file-name-base' is now mandatory and no
 longer defaults to 'buffer-file-name'.
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index adec632..dc23d2d 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -703,6 +703,7 @@ Iteration
 (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.
+Note that the @var{result} should not be used unless it makes use of @var{var}.
 Here is an example of using @code{dotimes} to do something 100 times:
 
 @example
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index bf85b00..f74214e 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1712,9 +1712,10 @@ Iteration
 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.  Note that the @var{result}
+should not be used unless it makes use of @var{var}.
 @end defmac
 
 @defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
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 @@ dotimes
 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 @@ dotimes
 @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
-@code{dotimes} returns @code{value}, so the way to use
-@code{dotimes} 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
+@var{number} 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 @@ dotimes
 (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/test/lisp/filenotify-tests.el b/test/lisp/filenotify-tests.el
index 219fa74..fa1ac95 100644
--- a/test/lisp/filenotify-tests.el
+++ b/test/lisp/filenotify-tests.el
@@ -1129,14 +1129,16 @@ file-notify--test-with-events
             ;; 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 @@ mod-test-emacs
 
 (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))