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

[João Távora]

On Thu, Nov 9, 2023 at 1:36 PM Alan Mackenzie <acm@muc.de> wrote:
>
> Hello, João.
>
> On Thu, Nov 09, 2023 at 12:40:24 +0000, João Távora wrote:
> > On Thu, Nov 9, 2023 at 11:49 AM Dmitry Gutov <dmitry@gutov.dev> wrote:
>
> > > Improving cl-lib's documentation would be a welcome effort.
>
> > For sure, and not a hard one as well, as all those functions and
> > macros are pretty good, often flawless emulations of CL functions that
> > are impeccably documented in
>
> >   http://www.lispworks.com/documentation/HyperSpec/Front/
>
> > Which is of free access (though not of a compatible license, I
> > think).  But if people can point to the 5 most confusing functions
> > they think are poorly documented, I volunteer to rewrite the
> > docstrings for them.
>
> How much are you prepared to do?  I don't have a list of the _most_
> confusing doc strings, there are too many to chose from.  But starting
> at the start of cl-macs.el, we have:
>
> (i) cl--compiler-macro-list*; completely undocumented.
> (ii) cl--simple-expr-p: Talks about "side effects", but not what they
>   are side effects of.  Doesn't describe it's parameters or return
>   value.  It's unclear what it is that "executes quickly".
> (iii) cl--expr-contains: It's unclear what X and Y are, and what "refers
>   to" means.
> (iv) cl--expr-contains-any; completely undocumented.
> (v) cl--expr-depends-p: It's unclear what X and Y are, though Y appears
>   to be some sort of container of symbols.  It's unclear what sort of
>   "dependency" the function handles, or what "may" means in the context.
>
> There are many more.

These are all internal functions and implementation details.  They're
not necessary at all for users of cl-lib.el, only for its developers.
What problem are you trying to solve by enhancing these docstrings?  I thought
the problem here was code that _used_ cl-lib.el, not hacking on
cl-lib.el itself.

João