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.