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

[Dmitry Gutov]

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.

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