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

[João Távora]

On Fri, Nov 10, 2023 at 12:13 PM Alan Mackenzie <acm@muc.de> wrote:
>
> Hello, João.
>
> On Thu, Nov 09, 2023 at 13:41:48 +0000, João Távora wrote:
> > 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.
>
> So, you're not prepared to rewrite their doc strings as you promised
> yesterday, any more.

I thought the whole problem is that code using cl-lib.el is hard to use.
You said cl-labels was "obscure", so I was prepared to enhance its
docstring, yes.  That's a public macro.  Along with 4 other "obscure"
public ones.  Documentation cl-lib's implementation details is something
else entirely.  It doesn't hurt if there's suspicion that cl-lib.el is
misbehaving in function or efficiency.   But that's not the matter in
discussion here and it doesn't solve the presumed problem of not
understanding code that makes uses cl-lib.

> > What problem are you trying to solve by enhancing these docstrings?
> Being able to debug Emacs problems.

What problem specifically are you having trouble with?  What do you
ultimately want to achieve that you can't without docstrings for
cl-lib.el's implementation details.  This might be an XY problem
(https://en.wikipedia.org/wiki/XY_problem)

> cl-lib uses itself, and needs debugging too.  Debugging code that uses
> abstractions often requires penetrating these abstractions and checking
> their innards.

Well, no.  I don't go read OS source code whenever I have doubts
about how to use a system call or how to read a given piece of
code that uses that system call, I read the manual page for the system
call itself.  Just as I don't pull up a magnifying glass to check if
my CPU's transistors are doing what they should, I trust the data sheet
describing the instructions.  So, no, at least not desirably.  That's
the whole argument for good docstrings: that it relieves you from
having to penetrate innards  to understand a function's interface.
Feels a bit odd to be defending age-old ideas of encapsulation and
information-hiding here.

To summarize, I thought it would be absolutely clear that I volunteered
to write docstrings for public functions, public interfaces.  I'm
amazed it wasn't, but I apologize for the misunderstanding nonetheless.
Docstrings for things that the user sees, is confused by, finds
obscure, etc. Give me 5 of  those, and I'll rework their docstrings for
clarity.  I suggest cl-labels since you singled it out and some
sequence manipulating functions which just say: "Keywords supported:
:test :test-not :key :start :end :from-end" but don't explain what
each of those keyword arguments do.

Another useful thing would be to extend eldoc support in Elisp mode
to be able to highlight the currently active keyword argument.  I'll
also look into that, but no promises.

Thanks,
João