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

[Alan Mackenzie]

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.

> João

-- 
Alan Mackenzie (Nuremberg, Germany).