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

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

[Drew Adams]

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.

In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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.

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

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 747 bytes --]

Michael Heerdegen <michael_heerdegen@web.de> writes:

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

The documentation of `seq-reduce' is probably not perfect, but at least
it tries to explain what reducing means:

    Return the result of calling FUNCTION with INITIAL-VALUE and the
    first element of SEQUENCE, then calling FUNCTION with that result and
    the second element of SEQUENCE, then with that result and the third
    element of SEQUENCE, etc.

    If SEQUENCE is empty, return INITIAL-VALUE and FUNCTION is not called.

Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

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

[Drew Adams]

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

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

[Drew Adams]

> >> 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.
> 
> The documentation of `seq-reduce' is probably not perfect, but at least
> it tries to explain what reducing means:
> 
>     Return the result of calling FUNCTION with INITIAL-VALUE and the
>     first element of SEQUENCE, then calling FUNCTION with that result and
>     the second element of SEQUENCE, then with that result and the third
>     element of SEQUENCE, etc.
> 
>     If SEQUENCE is empty, return INITIAL-VALUE and FUNCTION is not called.

Much better, yes.  This is the right level at which to describe what
it does for most programmers, IMO.

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

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 644 bytes --]

On 2016-07-18 06:41, Drew Adams wrote:
> 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.

What about adding a few examples? Something like this maybe?

    (cl-reduce f '(1 2 3 4 5))
      ↔ (f (f (f (f 1 2) 3) 4) 5)

    (cl-reduce f '(1 2 3 4 5) :initial-value 0)
      ↔ (f (f (f (f (f 0 1) 2) 3) 4) 5)

    (cl-reduce f '(1 2 3 4 5) :from-end t)
      ↔ (f 1 (f 2 (f 3 (f 4 5))))

    (cl-reduce f '(1 2 3 4 5) :from-end t :initial-value 0)
      ↔ (f 1 (f 2 (f 3 (f 4 (f 5 0)))))


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 235 bytes --]

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

> Much better, yes.  This is the right level at which to describe what
> it does for most programmers, IMO.

I pushed a commit in master (I haven't done anything WRT the texinfo
file).

Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

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

[Drew Adams]

> > 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.
> 
> What about adding a few examples? Something like this maybe?
> 
>     (cl-reduce f '(1 2 3 4 5))
>       ↔ (f (f (f (f 1 2) 3) 4) 5)
> 
>     (cl-reduce f '(1 2 3 4 5) :initial-value 0)
>       ↔ (f (f (f (f (f 0 1) 2) 3) 4) 5)
> 
>     (cl-reduce f '(1 2 3 4 5) :from-end t)
>       ↔ (f 1 (f 2 (f 3 (f 4 5))))
> 
>     (cl-reduce f '(1 2 3 4 5) :from-end t :initial-value 0)
>       ↔ (f 1 (f 2 (f 3 (f 4 (f 5 0)))))

LGTM - except that f should be quoted as an arg to `cl-reduce'.
E.g. (cl-reduce 'f '(1 2 3)).

And a shorter list makes things a tiny bit simpler: (1 2 3).

(And I'm not crazy about the too-short double arrow, personally.)

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

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1153 bytes --]

On 2016-07-18 16:02, Drew Adams wrote:
>>> 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.
>>
>> What about adding a few examples? Something like this maybe?
>>
>>     (cl-reduce f '(1 2 3 4 5))
>>       ↔ (f (f (f (f 1 2) 3) 4) 5)
>>
>>     (cl-reduce f '(1 2 3 4 5) :initial-value 0)
>>       ↔ (f (f (f (f (f 0 1) 2) 3) 4) 5)
>>
>>     (cl-reduce f '(1 2 3 4 5) :from-end t)
>>       ↔ (f 1 (f 2 (f 3 (f 4 5))))
>>
>>     (cl-reduce f '(1 2 3 4 5) :from-end t :initial-value 0)
>>       ↔ (f 1 (f 2 (f 3 (f 4 (f 5 0)))))
> 
> LGTM - except that f should be quoted as an arg to `cl-reduce'.
> E.g. (cl-reduce 'f '(1 2 3)).
> 
> And a shorter list makes things a tiny bit simpler: (1 2 3).
> 
> (And I'm not crazy about the too-short double arrow, personally.)

I wasn't sure about the sort list; I actually found things more confusing that way.  Should this go in the ELisp manual, or in the docstring?
No strong feelings about the double arrow, and fine with me for quoting f.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Drew Adams]

> I wasn't sure about the s[h]ort list; I actually found things more
> confusing that way.

I wonder why?  But OK by me not to shorten.

> Should this go in the ELisp manual, or in the docstring?

Doesn't matter to me.  Maybe the manual is better.

And isn't the CL manual the proper manual, not the Elisp manual?

IMHO, it would help if manual entries for Common-Lisp emulation
stuff had links to the most relevant CLTL2 sections that specify it.

E.g., in this case, our CL manual would point here:
https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node143.html.

It is appropriate for our CL doc to both (1) point to the Common-Lisp
spec for the corresponding thingy and (2) point out any differences
between our emulation and the thing it emulates.

IMHO, not doing this is not doing our job properly, not helping
Emacs-Lisp users use our CL emulation.

> No strong feelings about the double arrow, and fine with me for quoting f.
 
Not quoting f is not an option.  If f is a variable bound to a function
then (f a b c) raises an error.  (This is not Scheme.)

  (setq b #'car)
  (b '(1 2 3))
  Symbol's function definition is void: b

If b is an fboundp symbol then (b '(1 2 3)) => 1.

When you pass a function-valued argument to `cl-reduce' it is the
boundp value of that _variable_ (symbol arg) that is passed, not
the fboundp value of the symbol arg.

The only thing that works a bit like what a Scheme user might
expect in this regard is the use of a lambda at the head of the
list:

((lambda (xs) (car xs)) '(1 2 3)) = 1.

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

[Stefan Kangas]

close 24014 28.1
thanks

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.
>>
>> The documentation of `seq-reduce' is probably not perfect, but at least
>> it tries to explain what reducing means:
>>
>>     Return the result of calling FUNCTION with INITIAL-VALUE and the
>>     first element of SEQUENCE, then calling FUNCTION with that result and
>>     the second element of SEQUENCE, then with that result and the third
>>     element of SEQUENCE, etc.
>>
>>     If SEQUENCE is empty, return INITIAL-VALUE and FUNCTION is not called.
>
> Much better, yes.  This is the right level at which to describe what
> it does for most programmers, IMO.

Nicolas updated the docstring, and I have now done the same change in
cl.texi on the emacs-28 branch (commit 43914ab01f).

It is the same text as above, just formatted for texinfo, so it should
be understandable to us mere programmers.

I'm consequently closing this bug report.