Re: What's missing in ELisp that makes people want to use cl-lib?

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Thu, 16 Nov 2023 21:58:51 +0000
> Cc: Michael Heerdegen <michael_heerdegen@web.de>, emacs-devel 
> <emacs-devel@gnu.org>
> 
> On Thu, Nov 16, 2023 at 4:42 PM Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > ?? There's a whole section in the ELisp manual called "Sequence
> > Functions", which documents the seq-* functions.
> 
> Yes, but from a custom sequence implementors perspective, 
> the "best" documentation is still that bit in the header, 
> which describes "you must implement these to get a working 
> custom sequence".
> 
> So while the Elisp manual addresses custom sequences
> (very briefly -- it just tells the user to look up generic
> functions) it spends most time describing the generic 
> functions one by one, and while that's important, it's 
> just not enough.

Feel free to suggest improvements and additions to what we have.  Such
improvements are always welcome here.  I just answered your original
question, viz.:

> > seq.el's documentation is where?  I don't see it.

which seemed to imply that you didn't know at all that we have seq.el
functions described in the manual.

> It doesn't talk about the guarantees that the framework 
> offers with respect to when they are called, or if they 
> are called at all. For example, while I didn't read the 
> whole thing, I don't think it is stated that custom sequences
> based on Lisp lists need many more gf implementations 
> than others, else they simply won't work (because of 
> list-specific shortcutting optimizations only found 
> when reading the seq.el code).  Nor is it stated that, for 
> any representation,  :around methods are probably a bad
> idea. Nor is it stated that if you just implement the bare
> minimum (which is described in seq.el's header) you will 
> likely get very poor performance.

It says this:

     All functions defined in this library are free of side-effects; i.e.,
  they do not modify any sequence (list, vector, or string) that you pass
  as an argument.  Unless otherwise stated, the result is a sequence of
  the same type as the input.  For those functions that take a predicate,
  this should be a function of one argument.

     The ‘seq.el’ library can be extended to work with additional types of
  sequential data-structures.  For that purpose, all functions are defined
  using ‘cl-defgeneric’.  *Note Generic Functions::, for more details
  about using ‘cl-defgeneric’ for adding extensions.

If this is not enough, once again, please feel free to suggest
improvements and extensions.

> Such a manual is where one would find sentences like 
> "to make a working custom sequence that is accepted by
> any seq-* call, the user must add implementations to 
> the following N generics.  To get good performance 
> you must also add implementations to these other M 
> generics".

Do you see something like that in other Lisp-related manuals we have?
Does cl.info has this information regarding cl-lib?

I think the answer is NO, because we generally don't say such things
in our manuals, except in rare exceptional cases (which the seq.el one
isn't, IMNSHO).  Perhaps we should, but then we have a lot of work to
do on our manuals, and that work is not only the necessary writeups,
but also non-trivial research and analysis.  Look how much effort was
needed to perform a similar analysis on seq.el.  Volunteers are
welcome to do the same in other places, and suggest additions to the
manuals for any significant findings.