bug#42324: 26.3; Doc string of `seq-concatenate'

bug#42324: 26.3; Doc string of `seq-concatenate'

[Drew Adams]

C-h f seq-concatenate
___

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

 (seq-concatenate TYPE SEQUENCE...)

 Concatenate SEQUENCES into a single sequence of type TYPE.
 TYPE must be one of following symbols: vector, string or list.


 This is a generic function.

 Implementations:

 (type &rest sequences) in 'seq.el'.

 Undocumented
___

1. See bug #42323 for the problem of the unhelpful, implicit reference
   to CL implementations and "generic function".

2. The doc of `seq-concatenate' _really_ needs a description of how it
   differs from `cl-concatenate'.  That's completely unclear.

3. The doc says nothing about each SEQUENCE actually being automatically
   converted (by copying, presumably) into a real sequence:
   `seq-into-sequence'.  It's not clear what's allowed as SEQUENCE.

#2 is the main reason I filed this bug report.  What's the difference?
Why/when would you use one rather than the other?


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#42324: 26.3; Doc string of `seq-concatenate'

[Stefan Kangas]

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

> C-h f seq-concatenate
> ___
>
>  seq-concatenate is a compiled Lisp function in 'seq.el'.
>
>  (seq-concatenate TYPE SEQUENCE...)
>
>  Concatenate SEQUENCES into a single sequence of type TYPE.
>  TYPE must be one of following symbols: vector, string or list.
>
>
>  This is a generic function.
>
>  Implementations:
>
>  (type &rest sequences) in 'seq.el'.
>
>  Undocumented
> ___
>
> 1. See bug #42323 for the problem of the unhelpful, implicit reference
>    to CL implementations and "generic function".

Do we need two bugs to track that?  It looks to me like essentially the
same issue.

> 2. The doc of `seq-concatenate' _really_ needs a description of how it
>    differs from `cl-concatenate'.  That's completely unclear.

On current master I see:

cl-concatenate is an alias for ‘seq-concatenate’ in ‘cl-extra.el’.

> 3. The doc says nothing about each SEQUENCE actually being automatically
>    converted (by copying, presumably) into a real sequence:
>    `seq-into-sequence'.  It's not clear what's allowed as SEQUENCE.

I'm not sure I understand this.

> #2 is the main reason I filed this bug report.  What's the difference?
> Why/when would you use one rather than the other?

Best regards,
Stefan Kangas

bug#42324: 26.3; Doc string of `seq-concatenate'

[Drew Adams]

> > 1. See bug #42323 for the problem of the unhelpful, implicit reference
> >    to CL implementations and "generic function".
> 
> Do we need two bugs to track that?  It looks to me like essentially the
> same issue.

Point #1 is common to both bugs, i.e., it's a problem
for both doc strings.  But #1 is not the only problem
for `seq-concatenate'.  If you fix #1 in a general way,
so it is fixed for both doc strings (and hopefully
others), then you can close #42323.  But if only #1 is
fixed then #42324 isn't fixed.

That's why there are 2 bug reports.  I don't know how
#1 will be fixed, e.g. whether it will be fixed for
only this or that doc string or all relevant doc strings.

> > 2. The doc of `seq-concatenate' _really_ needs a description of how it
> >    differs from `cl-concatenate'.  That's completely unclear.
> 
> On current master I see:
> 
> cl-concatenate is an alias for ‘seq-concatenate’ in ‘cl-extra.el’.

I see.  That's not the case in the Emacs version of the
bug report.

Is that correct?  Does `seq-concatenate' correctly
implement Common Lisp `concatenate'?  If so, then the
alias is good.  If not, then `cl-concatenate' needs
to be fixed to correctly fit the bill.

> > 3. The doc says nothing about each SEQUENCE actually being automatically
> >    converted (by copying, presumably) into a real sequence:
> >    `seq-into-sequence'.  It's not clear what's allowed as SEQUENCE.
> 
> I'm not sure I understand this.

In Emacs 26.3, this is the definition of `seq-concatenate':

(cl-defgeneric seq-concatenate (type &rest sequences)
  "Concatenate SEQUENCES into a single sequence of type TYPE.
TYPE must be one of following symbols: vector, string or list.

\n(fn TYPE SEQUENCE...)"
  (apply #'cl-concatenate
         type
         (seq-map #'seq-into-sequence sequences)))

First, in this Emacs version clearly `cl-concatenate' can't
be the same as `seq-concatenate'.

Second, `seq-into-sequence' seems like a really bad name,
for something that either raises an error or is `identity'.
The name suggests that something that is not quite a sequence
gets converted into a sequence.  I was misled by the name,
I guess.

Well, maybe not.  Apparently `cl-defgeneric' just defines
_default_ behavior.  So the point remains: the doc string
should say that the SEQUENCES are first converted into
proper sequences (in some way), which are then passed to
`cl-concatenate'.  And it should probably state the
default behavior of just raising an error if not already
a sequence.

I'd say, overall, that I don't understand the behavior
by reading the doc string.  And we should.  We shouldn't
have to guess that `cl-defgeneric' is used, and so the
behavior might actually be this, that, or the other
thing (or whatever the case may be).  The do string
should say what the behavior is, including what it _can
be_, if `cl-defgeneric' allows it to end up differing,
depending on SEQUENCES.

> > #2 is the main reason I filed this bug report.  What's the difference?
> > Why/when would you use one rather than the other?

bug#42324: 26.3; Doc string of `seq-concatenate'

[Eli Zaretskii]

> Date: Tue, 25 Aug 2020 15:46:59 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 42324@debbugs.gnu.org
> 
> In Emacs 26.3, this is the definition of `seq-concatenate':
> 
> (cl-defgeneric seq-concatenate (type &rest sequences)
>   "Concatenate SEQUENCES into a single sequence of type TYPE.
> TYPE must be one of following symbols: vector, string or list.
> 
> \n(fn TYPE SEQUENCE...)"
>   (apply #'cl-concatenate
>          type
>          (seq-map #'seq-into-sequence sequences)))

If the bug report is about the doc string, please don't show the
implementation as your evidence.  The issue is (or should be) with the
text of the doc string.

> I'd say, overall, that I don't understand the behavior
> by reading the doc string.

Which part(s) of the doc string's text are unclear?  The text is short
and IMO very clear, so I'm puzzled by this bug report to begin with.

In general, it sounds like what you are after is to understand the
implementation, and that can only be done by reading the code.  In
that case, I see no bug to report here.

bug#42324: 26.3; Doc string of `seq-concatenate'

[Drew Adams]

> > In Emacs 26.3, this is the definition of `seq-concatenate':
> >
> > (cl-defgeneric seq-concatenate (type &rest sequences)
> >   "Concatenate SEQUENCES into a single sequence of type TYPE.
> > TYPE must be one of following symbols: vector, string or list.
> >
> > \n(fn TYPE SEQUENCE...)"
> >   (apply #'cl-concatenate
> >          type
> >          (seq-map #'seq-into-sequence sequences)))
> 
> If the bug report is about the doc string, please don't show the
> implementation as your evidence.  The issue is (or should be) with the
> text of the doc string.

You took that out of context.  The context was the
(apparent) change since 26.3, when the bug was reported.
And the bug report is (only) about the doc, including
differences `seq-concatenate' vs `cl-concatenate'.

IF those are now the same thing, and that's said
in the doc (which it apparently is), then #2 of this
bug report disappears.

And #1 is the same as bug #42323.  See also #3.

> > I'd say, overall, that I don't understand the behavior
> > by reading the doc string.
> 
> Which part(s) of the doc string's text are unclear?  The text is short
> and IMO very clear, so I'm puzzled by this bug report to begin with.
> 
> In general, it sounds like what you are after is to understand the
> implementation, and that can only be done by reading the code.  In
> that case, I see no bug to report here.

All of #1, #2, and #3 are only about the doc string.

In any case, the real difficulty is #1, which is bug
#42323.  If that gets fixed properly, AND if
`seq-concatenate' is now exactly the same as
`cl-concatenate' and that's stated in the doc, then
things should be clear.

What's discussed in this thread is, however, relevant
to bug #42323, I think.  Including if the behavior
can change depending on SEQUENCES, as seems to be
the case from looking at the code and `cl-defgeneric'.

The bug report is not about the implementation at
all.  It's about the doc specifying the behavior.

bug#42324: 26.3; Doc string of `seq-concatenate'

[Eli Zaretskii]

> Date: Wed, 26 Aug 2020 11:14:52 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, 42324@debbugs.gnu.org
> 
> The bug report is not about the implementation at
> all.  It's about the doc specifying the behavior.

The doc string seems clear to me.  And since I don't understand what
are #1, #2, and #3 in your notation, I cannot continue this discussion
in any useful way, sorry.

bug#42324: 26.3; Doc string of `seq-concatenate'

[Drew Adams]

> > The bug report is not about the implementation at
> > all.  It's about the doc specifying the behavior.
> 
> The doc string seems clear to me.  And since I don't understand what
> are #1, #2, and #3 in your notation, I cannot continue this discussion
> in any useful way, sorry.

From the bug report (and elsewhere in the thread I
also made clear what #1, #2, and #3 referred to):

  1. See bug #42323 for the problem of the unhelpful,
     implicit reference to CL implementations and
     "generic function".

  2. The doc of `seq-concatenate' _really_ needs a
     description of how it differs from `cl-concatenate'.
     That's completely unclear.

  3. The doc says nothing about each SEQUENCE actually
     being automatically converted (by copying, presumably)
     into a real sequence: `seq-into-sequence'.  It's
     not clear what's allowed as SEQUENCE.

  #2 is the main reason I filed this bug report.  What's the difference?
  Why/when would you use one rather than the other?

bug#42324: 26.3; Doc string of `seq-concatenate'

[Eli Zaretskii]

> Date: Wed, 26 Aug 2020 11:37:39 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, 42324@debbugs.gnu.org
> 
> > The doc string seems clear to me.  And since I don't understand what
> > are #1, #2, and #3 in your notation, I cannot continue this discussion
> > in any useful way, sorry.
> 
> >From the bug report (and elsewhere in the thread I
> also made clear what #1, #2, and #3 referred to):
> 
>   1. See bug #42323 for the problem of the unhelpful,
>      implicit reference to CL implementations and
>      "generic function".

There's no reference to CL in the current doc string.

>   2. The doc of `seq-concatenate' _really_ needs a
>      description of how it differs from `cl-concatenate'.
>      That's completely unclear.

There's no reference to cl-concatenate in the current doc string.

>   3. The doc says nothing about each SEQUENCE actually
>      being automatically converted (by copying, presumably)
>      into a real sequence: `seq-into-sequence'.

Why should it mention something like that?

>      It's
>      not clear what's allowed as SEQUENCE.

Any sequence, obviously.  Anyway, the current doc string spells it
out:

  TYPE must be one of following symbols: vector, string or list.

>   #2 is the main reason I filed this bug report.  What's the difference?
>   Why/when would you use one rather than the other?

I guess that problem no longer exists with the current doc string.

bug#42324: 26.3; Doc string of `seq-concatenate'

[Lars Ingebrigtsen]

The doc string of seq-concatenate seems excessively clear to me, so I'm
closing this bug report.

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