GNU bug report logs - #24014
24.5; doc string of `cl-reduce'

Previous Next

Full log

Message #14 received at 24014 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 24014 <at> debbugs.gnu.org
Subject: RE: 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.