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

[Alan Mackenzie]

Hello, Dmitry.

On Thu, Nov 09, 2023 at 13:48:34 +0200, Dmitry Gutov wrote:

> On 09/11/2023 12:34, Alan Mackenzie wrote:
> > As a concrete plan, I would propose the following for discussion:

> > We should deprecate those functions/macros/variables in cl-lib that have
> > no doc string, or a substandard one.  This includes "internal" functions,
> > too.  Also to be deprecated are obscure functions/m/v (such as
> > cl-labels).

> I'm not sure we can remove cl-labels -- it's useful enough for the cases 
> where it does help, and there are callers inside and outside of Emacs.

> Whatever other removals, would probably need to be discussed case-by-case.

There are probably too many such functions/macros/variables to make that
practicable.  If we did do this, the discussion for each f/m/v would
likely balloon out into a thread as long as this one, and nothing much
would get done.

> > Having done this, we recode code currently using those deprecated f/m/v.

> > (Here a "substandard" doc string is contrasted with an adequate one,
> > which does all of the following:
> > (i) It says what the function/macro_does_, or what the variable_is_.
> > (ii) It describes the form and meaning of each parameter, and its
> >    relationship to (i).
> > (iii) If the return value is significant, it describes this.
> > (iv) It describes all effects on the global state, such as where it
> >    writes results to, and suchlike.)

> Improving cl-lib's documentation would be a welcome effort.

Yes, people have been saying this for years.  I wrote a chapter on
cl-print.el for cl.info a couple of months back.  Other than that nobody
seems prepared to do anything much on this front.

What is needed is a sustained effort from a cl-lib enthusiast to fix the
50 - 100 doc strings which are missing or substandard.  Well, João has
offered to start off with 5 doc strings, which is good.  Maybe something
will come of that.

-- 
Alan Mackenzie (Nuremberg, Germany).