bug#24014: 24.5; doc string of `cl-reduce'

[Michael Heerdegen]

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

> Please state in the doc string what the function does.  IOW,
> explain/describe/specify what "reduce" means.  Do not suppose that Emacs
> Lisp users are all familiar with functional programming etc.
>
> If _you_ understand it, you should be able to describe it in a couple of
> sentences.  It's not a complicated thing, but just repeating the word
> "reduce" from the function name is not sufficient - not helpful.

I also find the explanation in the manual confusing:

  "This function combines the elements of SEQ using an associative
  binary operation."

The function does _not_ need to be associative.  The sentence later:

  "If ‘:from-end’ is true, the reduction is right-associative instead
  of left-associative."

makes sense, of course, but above, the word "associative" does not mean
more than "any", and without reading the later text, it can easily be
misunderstood.


Michael.