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

[Drew Adams <drew.adams@oracle.com>]

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