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

[Alan Mackenzie <acm@muc.de>]

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.

> What problem are you trying to solve by enhancing these docstrings?

Being able to debug Emacs problems.

> I thought the problem here was code that _used_ cl-lib.el, not hacking
> on cl-lib.el itself.

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

Still, if you're not prepared to fix doc strings in internal functions,
here are five external functions with inadequate doc strings:

(i) cl-fill: The doc string misnames some of the parameters.  It is
unclear what "fill" means, and the forms of CL-SEQ and CL-ITEM aren't
specified.  Is each element of CL-SEQ "filled" with the entirety of
CL-ITEM, or what?  Finally, there is no documentation of CL-KEYS, beyond
stating that two particular keywords are "supported", whatever that
means.  What do :start and :end actually do?  The return value is not
specified.

(ii) cl-replace: Much the same problems as for cl-fill.

(iii) cl-remove: Same again.  Additionally, it is not specified what an
"occurrence" is; this presumably involves some equality test, and which
one is used is not specified.  Again the effect of the keywords is
unspecified.  There are keywords used in its code which aren't listed in
the doc string, namely :if and :if-not.

(iv) cl-remove-if: Much the same again.

(v) cl-remove-if-not: ... and again.

I found these simply by starting at the beginning of cl-seq and listing
pretty much each external function I found in a simple search.  There are
a lot more like these.

Still, even having just those five things properly documented would be
worthwhile.  Thanks for volunteering to do this!

> João

-- 
Alan Mackenzie (Nuremberg, Germany).