[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Drew Adams
Subject: bug#24014: 24.5; doc string of `cl-reduce'
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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]