Re: Plan of attack or division of labor for documenting cl-lib

[Bob Rogers <rogers@rgrjr.com>]

   From: João Távora <joaotavora@gmail.com>
   Date: Sat, 2 Dec 2023 21:54:17 +0000

   On Sat, Dec 2, 2023 at 8:16 PM Bob Rogers <rogers@rgrjr.com> wrote:

   >    I was wondering if we should portion out work so that no one
   >    duplicates effort?

   > Good idea.

   Yes.  Various notes, in no particular order of importance:

   * I've got a number of docstring already done in a branch
     called feature/cl-lib-improvements, mostly to cl-seq.el

Excellent; great to see you've been thinking (and working) along these
lines.

   . . .

   * It is also useful to note that there is a open-source
     version of the Common Lisp specification with a license
     that is much more permissive than LispWork's Hyperspec . . 

Nice; thanks.

   * When editing docstrings, I'd say it's a good idea to edit
     them (even if they've been already been touched by someone
     else) so that the language and formulations of common elements
     are consistent.  For example, I've been editing the last
     line of docstrings so they look like:

       (fn FUNCTION SEQ &key FROM-END START END INITIAL-VALUE KEY...)

     instead of

       (fn FUNCTION SEQ [KEYWORD VALUE]...)"

     And then I try relatively hard to describe the keyword arguments
     (of 'cl-reduce', in this case) in the order that they appear in
     this list.

Yes; seems to me that just amounts to bringing them up to Emacs
documentation standards.

   * Sometimes I also add this formulaic reference to the manual:

       TEST and KEY are keyword arguments.  See info node
       `(cl) Program Structure > Argument Lists' for details.

     But I've not yet decided if it's a good idea to repeat this
     in every docstring.  Maybe, given the apparent unfamiliarity
     with keyword arguments by some Emacs developers.

Sigh.  This wouldn't be necessary if &key were to appear in emacs 30
. . . but I suppose we shouldn't count on that.

   * Be very careful when describing these utils as some of
     them aren't perfect implementations of the CL spec and we
     may need to remain bug-compatible . . .

Good point.

     . . . In the case of cl-mismatch I'm thinking we should fix the
     bugs and deal with any flak.

Bug-fixing is good, but it seems to me this is affects a controversial
area of the code.  Perhaps it would be better to separate documentation
and unrelated code changes?

   * Unit tests are very welcome too.  Place them in

       test/lisp/emacs-lisp/cl-lib-tests.el
       test/lisp/emacs-lisp/cl-seq-tests.el
       test/lisp/emacs-lisp/cl-macs-tests.el

   Let me know what you think of this plan,
   João

I like it; count me in.

					-- Bob