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

[João Távora]

On Fri, Nov 10, 2023 at 3:47 PM Alan Mackenzie <acm@muc.de> wrote:
>
> On Fri, Nov 10, 2023 at 15:14:05 +0000, João Távora wrote:
> > On Fri, Nov 10, 2023 at 3:11 PM Alan Mackenzie <acm@muc.de> wrote:
>
> > > > 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.
>
> > Oh then I missed that second set in all this jumble.  Can you please
> > post it again?
>
> It's in my post in this thread posted at Date: Fri, 10 Nov 2023 12:13:25
> +0000.
>
> Or to be found at
> https://lists.gnu.org/archive/html/emacs-devel/2023-11/msg00439.html.

Alright, here are two of the five functions documented in a patch.
Will look at the other 3 later.  By the way, if you have a web browser,
the so-called Common Lisp hyperspec is an excellent resource
to learn to work with CL functions.

Here is the doc for FILL and REPLACE:

  http://www.lispworks.com/documentation/HyperSpec/Body/f_fill.htm
  http://www.lispworks.com/documentation/HyperSpec/Body/f_replac.htm

Disclamer:  I'm open to tweaking these docstrings I wrote to
some reasonable degree, like grammar fixes, reordering sentences,
 etc.  Constructive criticism only. I will not indulge endless
hair-splitting, bikeshedding or deep personal considerations of
what proper docstrings should contain and look like, especially
if I suspect it is fueled by any deep disdain (or "generic aversion"
as someone put it) of the cl-lib.el library, such as has been patent
so far in some posts of this discussion so far.

IOW I agree with you that the current docstrings are subpar, so
this is why I volunteered to enhance them, but this is my honest
writing and my own considerations of what a good docstring should
look like, based on many years experience with Lisp and Emacs, and
how it may help a honest user of these functions put them to good
use or read code containing them.

And now the patch for 2 of the 5 functions you mentioned,
João

diff --git a/lisp/emacs-lisp/cl-seq.el b/lisp/emacs-lisp/cl-seq.el
index ec481121ae6..dd9f37b0a82 100644
--- a/lisp/emacs-lisp/cl-seq.el
+++ b/lisp/emacs-lisp/cl-seq.el
@@ -162,9 +162,19 @@ cl-reduce

 ;;;###autoload
 (defun cl-fill (cl-seq cl-item &rest cl-keys)
-  "Fill the elements of SEQ with ITEM.
-\nKeywords supported:  :start :end
-\n(fn SEQ ITEM [KEYWORD VALUE]...)"
+  "Replace elements of SEQ between START and END with ITEM.
+SEQ is a Lisp sequence.  It is destructively modified and
+returned.
+
+START and END are indexes like in `aref' or `elt'.  They
+designate the subsequence of SEQ to operate on.  If END is nil,
+process the sequence to the end. They default to 0 and nil,
+respectively, meaning process the whole SEQ.
+
+START and END are keyword arguments.  See info node `(cl) Program
+Structure > Argument Lists' for details.
+
+\n(fn SEQ ITEM &key START END...)"
   (cl--parsing-keywords ((:start 0) :end) ()
     (if (listp cl-seq)
  (let ((p (nthcdr cl-start cl-seq))
@@ -182,10 +192,30 @@ cl-fill

 ;;;###autoload
 (defun cl-replace (cl-seq1 cl-seq2 &rest cl-keys)
-  "Replace the elements of SEQ1 with the elements of SEQ2.
-SEQ1 is destructively modified, then returned.
-\nKeywords supported:  :start1 :end1 :start2 :end2
-\n(fn SEQ1 SEQ2 [KEYWORD VALUE]...)"
+  "Replace the elements of SEQ1 with elements of SEQ2.
+SEQ1 and SEQ2 are both Lisp sequences.  SEQ1 is destructively
+modified and returned.
+
+START1, END1, START2 and END2 can be indexes like in `aref' or
+`elt'.  Each pair designates two subsequences of SEQ1 and SEQ2,
+respectively, to operate on.  If END1 or END2 is nil, consider
+the respective sequences to the end.
+
+Consecutive elements of the subsequence of SEQ1 are replaced by
+consecutive elements of the subsequence of SEQ2.
+
+If the subsequences vary in length, the shorter one determines
+how many elements are replaced.  Extra elements in either
+subsequence are ignored.
+
+START1 and START2 default to 0, END1 and END2 default to nil,
+meaning replace as much of SEQ1 as possible with elements from
+SEQ2.
+
+START1, END1, START2 and END2 are keyword arguments.  See info
+node `(cl) Program Structure > Argument Lists' for details.
+
+\n(fn SEQ1 SEQ2 &key START1 END1 START2 END2...)"
   (cl--parsing-keywords ((:start1 0) :end1 (:start2 0) :end2) ()
     (if (and (eq cl-seq1 cl-seq2) (<= cl-start2 cl-start1))
  (or (= cl-start1 cl-start2)