bug#72546: [PATCH] cond-star: Fix trivial typos in comments, checkdoc fixes and header/footer

[Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 322 bytes --]

Hi,

This patch improves documentation.  There is no change in functionality.
There are 3 categories:

Trivial typos in comments
Checkdoc fixes in docstrings
Addition of header/footer (Commentary section etc), also suggested by
checkdoc

If of interest please install, or otherwise provide suggestions for
further work.



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-trivial-typos-in-comments-checkdoc-fixes-and-hea.patch --]
[-- Type: text/x-diff, Size: 12817 bytes --]

From 5cea8fbac339e434e2e246c0101599abd2b17779 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Thu, 8 Aug 2024 23:01:13 +0100
Subject: [PATCH] Fix trivial typos in comments, checkdoc fixes and
 header/footer

* lisp/emacs-lisp/cond-star.el (cond*):
Add header and footer as per checkdoc fixes.

(match*, cond*-non-exit-clause-substance)
(cond*-convert-clause, cond*-convert-condition)
(cond*-match, cond*-subpat)
(cond*-used-within, cond-star):
Fix typos in comments, and apply checkdoc fixes
---
 lisp/emacs-lisp/cond-star.el | 84 ++++++++++++++++++++----------------
 1 file changed, 47 insertions(+), 37 deletions(-)

diff --git a/lisp/emacs-lisp/cond-star.el b/lisp/emacs-lisp/cond-star.el
index 6309b0d1a15..6c9af2638e9 100644
--- a/lisp/emacs-lisp/cond-star.el
+++ b/lisp/emacs-lisp/cond-star.el
@@ -1,4 +1,4 @@
-;;; -*-lexical-binding: t; -*-
+;;; cond-star.el --- Extended form of `cond' construct     -*-lexical-binding: t; -*-
 
 ;; Copyright (C) 1985-2024 Free Software Foundation, Inc.
 
@@ -20,22 +20,28 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
+;;; Commentary:
+
+;; Extended form of traditional Lisp `cond' construct.
+
 ;; Here is the list of functions the generated code is known to call:
 ;; car, cdr, car-safe, cdr-safe, nth, nthcdr, null, eq, equal, eql, =,
 ;; vectorp, length.
-;; It also uses these control and binding promitives:
+;; It also uses these control and binding primitives:
 ;; and, or, if, progn, let, let*, setq.
 ;; For regexp matching only, it can call string-match and match-string.
 
 ;;; ??? If a clause starts with a keyword,
-;;; should the element after the kwyword be treated in the usual way
-;;; as a pattern?  Curently `cond*-non-exit-clause-substance' explicitly
+;;; should the element after the keyword be treated in the usual way
+;;; as a pattern?  Currently `cond*-non-exit-clause-substance' explicitly
 ;;; prevents that by adding t at the front of its value.
 
+;;; Code:
+
 (defmacro cond* (&rest clauses)
   "Extended form of traditional Lisp `cond' construct.
 A `cond*' construct is a series of clauses, and a clause
-normally has the form (CONDITION BDOY...).
+normally has the form (CONDITION BODY...).
 
 CONDITION can be a Lisp expression, as in `cond'.
 Or it can be `(bind* BINDINGS...)' or `(match* PATTERN DATUM)'.
@@ -66,7 +72,7 @@ cond*
 
 (defmacro match* (pattern datum)
   "This specifies matching DATUM against PATTERN.
-It is not really a LIsp function, and it is meaningful
+It is not really a Lisp function, and it is meaningful
 only in the CONDITION of a `cond*' clause.
 
 `_' matches any value.
@@ -80,51 +86,51 @@ match*
   The match must cover the entire string from its first char to its last.
 ATOM (meaning any other kind of non-list not described above)
   matches anything `equal' to it.
-(rx REGEXP) uses a regexp specified in s-expression form,
+\(rx REGEXP) uses a regexp specified in s-expression form,
   as in the function `rx', and matches the data that way.
-(rx REGEXP SYM0 SYM1...) uses a regexp specified in s-expression form,
+\(rx REGEXP SYM0 SYM1...) uses a regexp specified in s-expression form,
   and binds the symbols SYM0, SYM1, and so on
   to (match-string 0 DATUM), (match-string 1 DATUM), and so on.
   You can use as many SYMs as regexp matching supports.
 
 `OBJECT  matches any value `equal' to OBJECT.
-(cons CARPAT CDRPAT)
+\(cons CARPAT CDRPAT)
   matches a cons cell if CARPAT matches its car and CDRPAT matches its cdr.
-(list ELTPATS...)
+\(list ELTPATS...)
   matches a list if the ELTPATS match its elements.
   The first ELTPAT should match the list's first element.
   The second ELTPAT should match the list's second element.  And so on.
-(vector ELTPATS...)
+\(vector ELTPATS...)
   matches a vector if the ELTPATS match its elements.
   The first ELTPAT should match the vector's first element.
   The second ELTPAT should match the vector's second element.  And so on.
-(cdr PATTERN)  matches PATTERN with strict checking of cdrs.
+\(cdr PATTERN)  matches PATTERN with strict checking of cdrs.
   That means that `list' patterns verify that the final cdr is nil.
   Strict checking is the default.
-(cdr-safe PATTERN)  matches PATTERN with lax checking of cdrs.
+\(cdr-safe PATTERN)  matches PATTERN with lax checking of cdrs.
   That means that `list' patterns do not examine the final cdr.
-(and CONJUNCTS...)  matches each of the CONJUNCTS against the same data.
+\(and CONJUNCTS...)  matches each of the CONJUNCTS against the same data.
   If all of them match, this pattern succeeds.
   If one CONJUNCT fails, this pattern fails and does not try more CONJUNCTS.
-(or DISJUNCTS...)  matches each of te DISJUNCTS against the same data.
+\(or DISJUNCTS...)  matches each of the DISJUNCTS against the same data.
   If one DISJUNCT succeeds, this pattern succeeds
   and does not try more DISJUNCTs.
   If all of them fail, this pattern fails.
-(COND*-EXPANDER ...)
+\(COND*-EXPANDER ...)
   Here the car is a symbol that has a `cond*-expander' property
   which defines how to handle it in a pattern.  The property value
   is a function.  Trying to match such a pattern calls that
   function with one argument, the pattern in question (including its car).
   The function should return an equivalent pattern
-  to be matched inetead.
-(PREDICATE SYMBOL)
+  to be matched instead.
+\(PREDICATE SYMBOL)
   matches datum if (PREDICATE DATUM) is true,
   then binds SYMBOL to DATUM.
-(PREDICATE SYMBOL MORE-ARGS...)
+\(PREDICATE SYMBOL MORE-ARGS...)
   matches datum if (PREDICATE DATUM MORE-ARGS...) is true,
   then binds SYMBOL to DATUM.
   MORE-ARGS... can refer to symbols bound earlier in the pattern.
-(constrain SYMBOL EXP)
+\(constrain SYMBOL EXP)
   matches datum if the form EXP is true.
   EXP can refer to symbols bound earlier in the pattern."
   (ignore datum)
@@ -147,7 +153,7 @@ cond*-non-exit-clause-substance
   (cond ((null (cdr-safe clause))   ;; clause has only one element.
          clause)
         ;; Starts with t or a keyword.
-        ;; Include t as the first element of the substancea
+        ;; Include t as the first element of the substance
         ;; so that the following element is not treated as a pattern.
         ((and (cdr-safe clause)
               (or (eq (car clause) t)
@@ -186,7 +192,7 @@ cond*-convert-clause
          ;; run unconditionally and handled as a cond* body.
          rest
          nil nil))
-    ;; Handle a normal (conditional exit) clauss.
+    ;; Handle a normal (conditional exit) clause.
     (cond*-convert-condition (car-safe clause) (cdr-safe clause) nil
                              rest (cond*-convert rest))))
 
@@ -212,7 +218,7 @@ cond*-convert-condition
            (let* ((bindings (cdr condition))
                   (first-binding (car bindings))
                   (first-variable (if (symbolp first-binding) first-binding
-                                   (car first-binding)))
+                                    (car first-binding)))
                   (first-value (if (symbolp first-binding) nil
                                  (cadr first-binding)))
                   (init-gensym (gensym "init"))
@@ -259,7 +265,7 @@ cond*-convert-condition
           ((eq pat-type 'match*)
            (cond*-match condition true-exps uncondit-clauses iffalse))
           (t
-           ;; Ordinary Lixp expression is the condition 
+           ;; Ordinary Lisp expression is the condition
            (if rest
                ;; A nonfinal exiting clause.
                ;; If condition succeeds, run the TRUE-EXPS.
@@ -310,8 +316,8 @@ cond*-match
     ;; unconditional clauses to follow,
     ;; and the pattern bound some variables,
     ;; copy their values into special aliases
-    ;; to be copied back at the start of the unonditional clauses.
-    (when (and uncondit-clauses true-exps 
+    ;; to be copied back at the start of the unconditional clauses.
+    (when (and uncondit-clauses true-exps
                (car raw-result))
       (dolist (bound-var (car raw-result))
         (push `(setq ,(gensym "ua") ,(car bound-var)) store-value-swap-outs)
@@ -320,7 +326,7 @@ cond*-match
     ;; Make an expression to run the TRUE-EXPS inside our bindings.
     (if store-value-swap-outs
         ;; If we have to store those bindings' values in aliases
-        ;; for the UNCONDIT-CLAUSES, ;; do so inside these bindigs.
+        ;; for the UNCONDIT-CLAUSES, ;; do so inside these bindings.
         (setq run-true-exps
               (cond*-bind-pattern-syms
                (car raw-result)
@@ -346,7 +352,7 @@ cond*-match
     ;; always run the UNCONDIT-CLAUSES.
     (if uncondit-clauses
         (setq expression
-              `(progn ,expression 
+              `(progn ,expression
                       (cond*-bind-pattern-syms
                        ,(if retrieve-value-swap-outs
                             ;; If we saved the bindings' values after the
@@ -437,7 +443,7 @@ cond*-subpat
              (if inside-or
                  (let (alias-gensym)
                    (if this-alias
-                       ;; Inside `or' subpattern, if this symbol already 
+                       ;; Inside `or' subpattern, if this symbol already
                        ;; has an alias for backtracking, just use that.
                        ;; This means the symbol was matched
                        ;; in a previous arm of the `or'.
@@ -512,7 +518,7 @@ cond*-subpat
          (let ((i 0) expressions)
            ;; Check for bad structure of SUBPAT here?
            (dolist (this-elt (cdr subpat))
-             (let ((result 
+             (let ((result
                     (cond*-subpat this-elt cdr-ignore bindings inside-or backtrack-aliases `(nth ,i ,data))))
                (setq bindings (car result))
                (push `(consp ,(if (zerop i) data `(nthcdr ,i ,data)))
@@ -538,7 +544,7 @@ cond*-subpat
                 (length (length elts))
                 expressions (i 0))
            (dolist (elt elts)
-             (let* ((result 
+             (let* ((result
                      (cond*-subpat elt cdr-ignore
                                    bindings inside-or backtrack-aliases `(aref ,i ,data))))
                (setq i (1+ i))
@@ -558,7 +564,7 @@ cond*-subpat
          (let (expressions)
            ;; Check for bad structure of SUBPAT here?
            (dolist (this-elt (cdr subpat))
-             (let ((result 
+             (let ((result
                     (cond*-subpat this-elt cdr-ignore bindings inside-or backtrack-aliases data)))
                (setq bindings (car result))
                (push (cdr result) expressions)))
@@ -566,7 +572,7 @@ cond*-subpat
         ;; Handle disjunction subpatterns.
         ((eq (car subpat) 'or)
          ;; The main complexity is unsetting the pattern variables
-         ;; that tentatively matche in an or-branch that later failed.
+         ;; that tentatively match in an or-branch that later failed.
          (let (expressions
                (bindings-before-or bindings)
                (aliases-before-or (cdr backtrack-aliases)))
@@ -575,13 +581,13 @@ cond*-subpat
              (let* ((bindings bindings-before-or)
                     bindings-to-clear expression
                     result)
-               (setq result 
+               (setq result
                      (cond*-subpat this-elt cdr-ignore bindings t backtrack-aliases data))
                (setq bindings (car result))
                (setq expression (cdr result))
                ;; Were any bindings made by this arm of the disjunction?
                (when (not (eq bindings bindings-before-or))
-                 ;; Ok, arrange to clear their backtrack aliases
+                 ;; OK, arrange to clear their backtrack aliases
                  ;; if this arm does not match.
                  (setq bindings-to-clear bindings)
                  (let (clearing)
@@ -644,7 +650,7 @@ cond*-subpat
            (cons (car result)
                  ;; This is the test condition.
                  (cond*-bind-around (car result) (nth 2 subpat)))))
-        (t 
+        (t
          (byte-compile-warn-x subpat "Undefined pattern type `%s' in `cond*'" (car subpat)))))
 
 ;;; Subroutines of cond*-subpat.
@@ -661,7 +667,7 @@ cond*-used-within
 This operates naively and errs on the side of overinclusion,
 and does not distinguish function names from variable names.
 That is safe for the purpose this is used for."
-  (cond ((symbolp exp) 
+  (cond ((symbolp exp)
          (let ((which (assq exp bindings)))
            (if which (list which))))
         ((listp exp)
@@ -705,3 +711,7 @@ cond*-un-backquote-list*
 
 
 
+
+(provide 'cond-star)
+
+;;; cond-star.el ends here
-- 
2.43.0