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

From: Drew Adams <[email-masked]>
Date: Sun, 17 Jul 2016 21:41:42 -0700 (PDT)

> > 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.

Yes, and even when such text is corrected, it is not necessarily
understandable by many users.  We should not assume that users
are math majors.

Even providing a functional-programming definition of `reduce' is
better than just describing it in abstract terms, if we can't come
up with a more down-to-earth description.