bug#45715: 27.1; Doc string of `dotimes'

bug#45715: 27.1; Doc string of `dotimes'

[Drew Adams]

  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).  Its use is deprecated.
                                            ^^^

In the last sentence, "its" is unclear.  Also, that sentence is missing
from the doc string of `cl-dotimes', even though it is present in the CL
Info manual.  And for `cl-dotimes' it should be made clear that this
"deprecation" is only about the Emacs Lisp emulation; the RETURN arg for
Common Lisp `dotimes' has not been deprecated.


In GNU Emacs 27.1 (build 1, x86_64-w64-mingw32)
 of 2020-08-12
Repository revision: 86d8d76aa36037184db0b2897c434cdaab1a9ae8
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static''

bug#45715: 27.1; Doc string of `dotimes'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

>   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).  Its use is deprecated.
>                                             ^^^
>
> In the last sentence, "its" is unclear.

Indeed, which is why it's

---
Finally RESULT is evaluated to get the return value (nil if
RESULT is omitted).  Using RESULT is deprecated, and may result
in compilation warnings about unused variables.
---

in Emacs 28.

> Also, that sentence is missing from the doc string of `cl-dotimes',
> even though it is present in the CL Info manual.  And for `cl-dotimes'
> it should be made clear that this "deprecation" is only about the
> Emacs Lisp emulation; the RETURN arg for Common Lisp `dotimes' has not
> been deprecated.

The two are different functions, so I don't see why.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45715: 27.1; Doc string of `dotimes'

[Noam Postavsky]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>>   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).  Its use is deprecated.
>>                                             ^^^
>>
>> In the last sentence, "its" is unclear.
>
> Indeed, which is why it's
>
> ---
> Finally RESULT is evaluated to get the return value (nil if
> RESULT is omitted).  Using RESULT is deprecated, and may result
> in compilation warnings about unused variables.
> ---
>
> in Emacs 28.

Also, I've backported that change to emacs-27, so it will show up in
27.2.

[1: 9d02e6c5ff]: 2020-11-18 15:45:48 -0500
  Further doc fixes for dotimes about RESULT
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=9d02e6c5ff2a8af78ca8a2c934970f8a46dcef55