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

[João Távora]

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

* In this branch I'm not only doing docstring improvements,
  but also reworking some internals, adding tests, and improving
  performance of some utilities.

* I propose we continue work on this branch, as it is easy
  to check (via vc-print-log, vc-version-history, or whatever
  your preferred Git tool is) what has already been done and
  by whom.

* To simplify things, I've pushed this branch over to my GitHub
  fork of Emacs

    https://github.com/joaotavora/emacs

  I can grant commit privileges to anyone who messages me
  privately with an interest in contributing this work.  Of
  course, you can also contribute patches to this branch via
  email (either via the bug tracker or by messaging me).

* After all the work has been done, or has reached some
  kind of milestone, we can integrate it in Emacs proper.

* It is important to check that you have your FSF copyright
  assignments in place.

* 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.
  I haven't yet checked the license to see if it is GPL compatible
  and thus if we can derive some work from it.  Here is the URL:

    https://cl-community-spec.github.io/pages/index.html

  even if the license isn't compatible it is a nice resource
  nonetheless.

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

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

* 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.  cl-loop is a notable example,
  but other more innocent-looking utils like cl-mismatch are
  affected.  In other cases, our utils go some unneeded extra miles
  like cl-set-difference guaranteeing relative order.  In this
  last case we shouldn't describe that in the docstring, IMO, but
  that feature must stay.  In the case of cl-mismatch I'm thinking
  we should fix the bugs and deal with any flak.

* 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