dolist considered harmful

[Stefan Monnier <monnier@IRO.UMontreal.CA>]

All this pcase-dolist discussion made me take a second look at dolist
and now I wondering whether we should keep it:

- The docstring is incomprehensible:

      Loop over a list.
      Evaluate BODY with VAR bound to each car from LIST, in turn.
      Then evaluate RESULT to get return value, default nil.

  I don't know how to loop over a list.  Did they mean to set the cdr
  of the last element so it loops back to the first element?
  "evaluate" is unclear (is it passed to   `eval`?  Then why not say it?
  What second arg is passed to `eval`?).
  but why evaluate it several times?
  Also, in which order?
  How does RESULT communicate the return value?
  Is it RESULT which defaults to nil or the return value?
  If the return value, then when does it default to nil?

- The docstring says nothing of what happens when LIST is not a list,
  yet a quick grep shows that most uses of dolist use for LIST a simple
  variable rather than a list.  What gives?

Since it can only be used when we're 100% sure that LIST is a LIST,
(and who can be sure of such a thing in a dynamic language like Emacs
Lisp), I think we'd be better off deprecating it and changing all uses
of dolist with a clear while+cdr loop that everyone can understand.


        Stefan