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

[Alan Mackenzie]

Hello again, João.

On Fri, Nov 10, 2023 at 14:35:38 +0000, João Távora wrote:
> On Fri, Nov 10, 2023 at 2:25 PM Alan Mackenzie <acm@muc.de> wrote:

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

> Those are not public functions, Alan.  Even Dmitry pointed that out
> immediately.

The second set were public functions.  And as Eli pointed out,
non-public functions need documenting too.

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

> Stop insinuating that.

You made an undertaking, the text of which was still in this thread
until you snipped it from your last post.

I now accept you won't be amending the doc strings I suggested, or
probably any others.  I think that's a shame, and I'm disappointed.

> I'm sorry you lost time looking at those functions (by why???).  But
> it's not my fault you have no distinction of public/private interface.

What sort of a smear is that meant to be?  It's just that I'm aware of
the need to document internal functions, you seem not to be.  As a
cl-lib enthusiast, you would have been best placed to fix this doc.

> Or at least not one I share.  But I do, and the Emacs documentation
> does.  The Emacs and Elisp manual doesn't describe '--' functions,
> period. Even checkdoc.el has this concept.  Docstrings for internal
> functions don't hurt, but they're not the essential parts to describe
> a library.  Surely not the first things you should focus on, because
> internals are by definition prone to one could re-implement all of
> cl-lib.el keeping the same interfaces and their docstrings with wholly
> new internals.  I don't know why am I'm having to clarify this.

I don't think there's much point continuing this bit of the conversation
any further.

> Anyway, take care, Alan.
> João

-- 
Alan Mackenzie (Nuremberg, Germany).