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