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

[Alan Mackenzie]

Hello, João.

On Fri, Nov 10, 2023 at 12:53:10 +0000, João Távora wrote:
> On Fri, Nov 10, 2023 at 12:13 PM Alan Mackenzie <acm@muc.de> wrote:

> > 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:

> > > > 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.

More precisely, it's hard to understand and to debug, precisely because
it uses cl-* functions.

> 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.

Ah, so your offer of fixing 5 doc strings is limited to obscure objects.
That wasn't clear from the outset, and wasn't what you said.

Documentation won't help cl-labels become any less obscure.  I've
debugged code using it, but I havn't any clue what it does.  There is
nothing about its functionality which sticks in memory.  Its name is
poor - "labels" isn't a verb, and what it does has nothing to do with
labels.

> 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.

It would solve part of the problem.

> > > 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)

I'm not having any specific problem at the moment.  The need for accurate
readable doc strings, particularly for code as difficult and obscure as
cl-*, should be self-evident.

I don't know what an "XY problem" is and can't be bothered to look up
your reference.  Thanks for not explaining clearly what you mean.

> > 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.

One Emacs bug I solved involved hacking into the Linux kernel.  The
solution to the bug was to upgrade to a specific kernel version or later.

> 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.

Total strawman argument.

> To summarize, I thought it would be absolutely clear that I volunteered
> to write docstrings for public functions, public interfaces.

No, it wasn't clear.

> 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 did so in my last post, and you've just snipped them without comment.
That's twice I've given you five bad doc strings, and you aren't acting
on either set.  That took a significant amount of my time.

Thanks.

It seems to me you are going back on your undertaking to amend these five
doc strings.

> 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.

That would certainly be useful, yes.

> 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.

That is something else entirely, unrelated to the poor quality of the doc
strings that we're talking about.

> Thanks,
> João

-- 
Alan Mackenzie (Nuremberg, Germany).