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

[Emanuel Berg]

João Távora wrote:

> These are all internal functions and implementation details.
> They're not necessary at all for users of cl-lib.el, only
> for its developers. What problem are you trying to solve by
> enhancing these docstrings? I thought the problem here was
> code that _used_ cl-lib.el, not hacking on cl-lib.el itself.

It is still nuch better than removing or rewriting it, so
let's do that.

We can use checkdoc to find out what docstrings are not
submitted or not correctly formated. Those should be pretty
quick fixes, to get away with those warnings.

After we have done that, if someone says some specific
docstring is still lacking we can focus on such individual
cases in more detail.

Here, to get the list from, e.g., cl-lib.el

(defun check-package-style ()
  (interactive)
  (let ((msg "Style check..."))
    (message msg)
    (checkdoc-current-buffer t)
    (message "%sdone" msg) ))

And the list is

cl-lib.el:133: Argument ‘keys’ should appear (as KEYS) in the doc string
cl-lib.el:160: All variables and subroutines might as well have a documentation 
string
cl-lib.el:166: All variables and subroutines might as well have a documentation 
string
cl-lib.el:197: All variables and subroutines might as well have a documentation 
string
cl-lib.el:197: All variables and subroutines might as well have a documentation 
string
cl-lib.el:226: Arguments occur in the doc string out of order
cl-lib.el:258: Argument ‘specs’ should appear (as SPECS) in the doc string
cl-lib.el:357: Argument ‘cl-func’ should appear (as CL-FUNC) in the doc string
cl-lib.el:450: Argument ‘rest’ should appear (as REST) in the doc string
cl-lib.el:488: Argument ‘cl-item’ should appear (as CL-ITEM) in the doc string
cl-lib.el:501: Argument ‘cl-new’ should appear (as CL-NEW) in the doc string
cl-lib.el:510: All variables and subroutines might as well have a documentation 
string
cl-lib.el:544: All variables and subroutines might as well have a documentation 
string
cl-lib.el:582: Probably "returns" should be imperative "return"

Here are all the cl-lib files

cl-extra.el
cl-generic.el
cl-indent.el
cl-lib.el
cl-loaddefs.el
cl-macs.el
cl-preloaded.el
cl-print.el
cl-seq.el

GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, cairo version 1.16.0)
of 2023-11-01 [commit
8eb9b82ce58a8323af21f52625a401e19e279a9c]

-- 
underground experts united
https://dataswamp.org/~incal