bug#42323: 26.3; Doc string of `seq-map'

bug#42323: 26.3; Doc string of `seq-map'

[Drew Adams]

C-h f seq-map

___

 seq-map is a compiled Lisp function in 'seq.el'.

 (seq-map FUNCTION SEQUENCE)

 Return the result of applying FUNCTION to each element of SEQUENCE.

 This is a generic function.

 Implementations:

 (function (sequence sequence)) in 'seq.el'.

 Undocumented

 (function sequence) in 'seq.el'.

 Undocumented
___

This doc doesn't stand on its own at all, beyond the first line.  It
doesn't look other Emacs doc strings.  It reads like some text generated
primitively by computer, with no real care about readers/users.

You can't have a clue about what "Implementations:" means, or the
individual implementation descriptions mean, unless you know about
`cl-defgeneric' and `cl-defmethod'.

At the very least there should be some link to the doc of those, or
(preferably) a description of what's involved by saying "This is a
generic function" - IF that's really necessary to understanding
`seq-map'.

Elisp users shouldn't be expected to be proficient in Common Lisp.  They
should be able to use and understand a function such as `seq-map'
without caring about its implementation.  seq.el constructs should be
describable and described on their own, ideally without requiring users
to dig into Common Lisp constructs.

Or IF understanding the implementation is really necessary, then the
fact that seq.el is implemented using cl constructs can't be elided.  Is
that really the case?  What we have now is a pretty useless, and quite
confusing, indirect/implicit reference to a cl implementation.  Why?
How is that helpful?


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#42323: 26.3; Doc string of `seq-map'

[Lars Ingebrigtsen]

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

> Or IF understanding the implementation is really necessary, then the
> fact that seq.el is implemented using cl constructs can't be elided.

This is the current doc string:

---
seq-map is a compiled Lisp function in ‘seq.el’.

(seq-map FUNCTION SEQUENCE)

  Other relevant functions are documented in the sequence group.

Return the result of applying FUNCTION to each element of SEQUENCE.

This is a generic function.

Implementations:

#'(sequence sequence) in ‘seq.el’.

Undocumented

#'sequence in ‘seq.el’.

Undocumented
---

It is, indeed, pretty obscure.  Like Drew, I wonder -- do we really have
to put these implementation details in the doc string at all?  Opinions?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#42323: 26.3; Doc string of `seq-map'

[Michael Heerdegen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> It is, indeed, pretty obscure.  Like Drew, I wonder -- do we really
> have to put these implementation details in the doc string at all?
> Opinions?

[ Such things were often knitted with hot needle by Stefan, left for us
as "an exercise", to formulate positive ]

Details: yes, it's good to have a list of implementations.  Obscure:
No.  The generated doc of implementations is indeed rather obscure.
Needs a good heart to fix:


> Implementations:
>
> #'(sequence sequence) in ‘seq.el’.
  ^^^^^^^^^^^^^^^^^^^^^

What syntax is that actually?  An accident?


> Undocumented

I would remove "Undocumented", it makes the text rather unreadable when
repeated often.

> #'sequence in ‘seq.el’.
>
> Undocumented

I wonder to what that is actually referring to.  There is only one
implementation in seq.el...?


Regards,

Michael.

bug#42323: 26.3; Doc string of `seq-map'

[Lars Ingebrigtsen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Details: yes, it's good to have a list of implementations.

The implementations are a way to optimise the functions -- they provide
no (well, little) information needed to use the functions.  So I'd argue
that they aren't needed by users.

That is, whether seq-map is optimised by doing

(defun seq-map (function sequence)
  (if (eq (type-of sequence) 'list)
      (seq-map-list ...)
    (seq-map-general ...)))

or whether that's achieved by defgeneric is immaterial to people using
seq-map: The interface to use remains identical.

> I wonder to what that is actually referring to.  There is only one
> implementation in seq.el...?

There's two:

(cl-defgeneric seq-map (function sequence)
(cl-defmethod seq-map (function (sequence sequence))

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#42323: 26.3; Doc string of `seq-map'

[Michael Heerdegen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> or whether that's achieved by defgeneric is immaterial to people using
> seq-map: The interface to use remains identical.

That's one side, yes.  OTOH, the information might matter in some cases,
e.g. when I want to know whether some interface is implemented for, say,
streams, in this case.  Or when the docstring mentions some special
properties of an interface for a certain class of objects the user needs
to know about.

Maybe we can find a compromise, e.g. a list of all implementations,
comma separated, not wasting much space, and then what we have now but
only for those implementations that have a docstring.  With the rule
that an implementation should have a docstring if and only if the
interface has some special property.  Does that make sense?


> > I wonder to what that is actually referring to.  There is only one
> > implementation in seq.el...?
>
> There's two:
>
> (cl-defgeneric seq-map (function sequence)
> (cl-defmethod seq-map (function (sequence sequence))

Ah, I didn't notice that the first is the default (maybe that could be
mentioned), and that the word "sequence" has two meanings here: one
includes e.g. streams (that's were the default is used) and one is the
classical sense that excludes streams and is faster than the default.

Michael.

bug#42323: 26.3; Doc string of `seq-map'

[Drew Adams]

FWIW, the notion of separation of interface from
implementation is not so clear for Lisp, and even
less so for Free Software Lisp.

Something implemented in "core" Emacs but in Lisp
is no more "the real thing" than the same thing
re-implemented by some user.  People can and do
reuse or modify "implementation" code.  And user
code sometimes does depend on how something is
"implemented".

In a way, take to an extreme, you could consider
the Lisp code distributed as part of GNU Emacs as
a "suggestion" to users.  (The C code as well,
but Lisp is particularly susceptible to, and even
invites, hacking, opportunistically or otherwise.)

bug#42323: 26.3; Doc string of `seq-map'

[Lars Ingebrigtsen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Maybe we can find a compromise, e.g. a list of all implementations,
> comma separated, not wasting much space, and then what we have now but
> only for those implementations that have a docstring.  With the rule
> that an implementation should have a docstring if and only if the
> interface has some special property.  Does that make sense?

Yeah, sounds good to me.  I came off way more categorical than I
intended -- I was mostly just musing out loud here.  

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#42323: 26.3; Doc string of `seq-map'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> Or IF understanding the implementation is really necessary, then the
>> fact that seq.el is implemented using cl constructs can't be elided.
>
> This is the current doc string:
>
> ---
> seq-map is a compiled Lisp function in ‘seq.el’.
>
> (seq-map FUNCTION SEQUENCE)
>
>   Other relevant functions are documented in the sequence group.
>
> Return the result of applying FUNCTION to each element of SEQUENCE.
>
> This is a generic function.
>
> Implementations:
>
> #'(sequence sequence) in ‘seq.el’.
>
> Undocumented
>
> #'sequence in ‘seq.el’.
>
> Undocumented
> ---
>
> It is, indeed, pretty obscure.  Like Drew, I wonder -- do we really have
> to put these implementation details in the doc string at all?  Opinions?

These details are now moved to the bottom of the help screen, below the
information that is immediately relevant.  Without a major re-design of
the help screen, I think that's as good as it gets for now:

    seq-map is a compiled Lisp function in ‘seq.el’.

    (seq-map FUNCTION SEQUENCE)

    Return the result of applying FUNCTION to each element of SEQUENCE.

      Other relevant functions are documented in the sequence group.



    This is a generic function.

    Implementations:

    #'(sequence sequence) in ‘seq.el’.

    Undocumented

    #'sequence in ‘seq.el’.

    Undocumented

I suggest closing this bug report as fixed in 28.1.

bug#42323: [External] : Re: bug#42323: 26.3; Doc string of `seq-map'

[Drew Adams]

> > It is, indeed, pretty obscure.  Like Drew, I wonder -- do we really
> > have to put these implementation details in the doc string at all?
> > Opinions?
> 
> These details are now moved to the bottom of the help screen, below the
> information that is immediately relevant.  Without a major re-design of
> the help screen, I think that's as good as it gets for now:
> ...
> 
> I suggest closing this bug report as fixed in 28.1.

I don't see how what you show fixes the bug in any
sense at all.  If the bug can't be fixed now, or no
one has the energy or motivation to fix it now, that
doesn't change the fact that the bug exists.

It's not fixed, IMO.  Your options, as I see it, are
(1) close as "won't fix" or (2) leave it open, in
hopes that someone, at some time, will find the will
and a way to fix it, and will do so.

My preference is almost always for #2.  Closing bugs
just to close bugs doesn't improve anything (IMO).
But it's your call, not mine.  I just don't agree
that the bug is fixed (based on what you showed), at
all.

bug#42323: [External] : Re: bug#42323: 26.3; Doc string of `seq-map'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 25 Sep 2021 16:10:06 +0000
> Cc: "42323@debbugs.gnu.org" <42323@debbugs.gnu.org>
> 
> > These details are now moved to the bottom of the help screen, below the
> > information that is immediately relevant.  Without a major re-design of
> > the help screen, I think that's as good as it gets for now:
> > ...
> > 
> > I suggest closing this bug report as fixed in 28.1.
> 
> I don't see how what you show fixes the bug in any
> sense at all.  If the bug can't be fixed now, or no
> one has the energy or motivation to fix it now, that
> doesn't change the fact that the bug exists.
> 
> It's not fixed, IMO.  Your options, as I see it, are
> (1) close as "won't fix" or (2) leave it open, in
> hopes that someone, at some time, will find the will
> and a way to fix it, and will do so.

I see no reason to continue the bikeshedding.  This bug is fixed, so
I'm closing it.

bug#42323: [External] : Re: bug#42323: 26.3; Doc string of `seq-map'

[Stefan Kangas]

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

> I don't see how what you show fixes the bug in any
> sense at all.  If the bug can't be fixed now, or no
> one has the energy or motivation to fix it now, that
> doesn't change the fact that the bug exists.
>
> It's not fixed, IMO.  Your options, as I see it, are
> (1) close as "won't fix" or (2) leave it open, in
> hopes that someone, at some time, will find the will
> and a way to fix it, and will do so.
>
> My preference is almost always for #2.  Closing bugs
> just to close bugs doesn't improve anything (IMO).
> But it's your call, not mine.  I just don't agree
> that the bug is fixed (based on what you showed), at
> all.

We can have thousands of bug reports about issues that are basically
there because that what the help screen fundamentally looks like and how
it works.

Or we can have a small number of bug reports that concretely proposes
how to improve the things that cause problems in the first place.

I prefer the latter, and therefore I prefer this bug report closed.

In this case, IMO some kind of folding or sections is what is needed.
Or there is some other general feature that we need.  IOW, this needs a
general solution, not N bug reports about all cases where the lack of
such a general solution cause issues.

bug#42323: [External] : Re: bug#42323: 26.3; Doc string of `seq-map'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I see no reason to continue the bikeshedding.  This bug is fixed, so
> I'm closing it.

Thanks.