From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#72546: [PATCH] cond-star: Fix trivial typos in comments, checkdoc fixes and header/footer Date: Fri, 09 Aug 2024 20:06:03 +0100 Message-ID: <8734nd8qjo.fsf@jeremybryant.net> Reply-To: Jeremy Bryant Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="907"; mail-complaints-to="usenet@ciao.gmane.io" To: 72546@debbugs.gnu.org, rms@gnu.org, eliz@gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Aug 09 21:06:53 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1scUwu-000AZc-AH for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 09 Aug 2024 21:06:53 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1scUwe-0000Vu-J3; Fri, 09 Aug 2024 15:06:36 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1scUwc-0000Vi-Jm for bug-gnu-emacs@gnu.org; Fri, 09 Aug 2024 15:06:34 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1scUwc-0006U9-9I for bug-gnu-emacs@gnu.org; Fri, 09 Aug 2024 15:06:34 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:Date:From:To:Subject; bh=ubxdUmXT/6R4mG6l3jH2BEmnhr/PE/ysfitrvT84VTw=; b=H+C83adyFeKtqFxieZlGJswH9O3h9GSPQZ6KRKCEpUl2RzSpZelv+Ff6KCI2CieNdUSdB9RulK7BqsLGFk4LWgXAxS837MaMyYbFqJiIIibH765WNeqSWDUChXuJQy6hKW07F03YMCGombvQbDewqNXC6b9EcPgJ8L3uKT3zEwcg7y5fwy/03m2c2uH7EqU1GyBbqf8sfhC0U934cvXIcD/5FhzEcKpIfV+N8x6xUS0pO8tEOtxh5TFbB8EUKWTSBE+IDfjS4T9Yfp8VuSusnh07eHPsIGBDXWgGm7rVECclKq9e0hpgdhXhYq9QGhjQjniTAadpdxFwIh4as+p7jg==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1scUx4-0002LC-EN for bug-gnu-emacs@gnu.org; Fri, 09 Aug 2024 15:07:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 09 Aug 2024 19:07:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 72546 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org, Richard Stallman , Eli Zaretskii Original-Received: via spool by submit@debbugs.gnu.org id=B.17232304078974 (code B ref -1); Fri, 09 Aug 2024 19:07:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 9 Aug 2024 19:06:47 +0000 Original-Received: from localhost ([127.0.0.1]:38608 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1scUwo-0002Ke-CQ for submit@debbugs.gnu.org; Fri, 09 Aug 2024 15:06:47 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:38366) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1scUwm-0002KV-1H for submit@debbugs.gnu.org; Fri, 09 Aug 2024 15:06:45 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1scUwJ-0000T2-6o for bug-gnu-emacs@gnu.org; Fri, 09 Aug 2024 15:06:15 -0400 Original-Received: from out-180.mta1.migadu.com ([95.215.58.180]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1scUwE-0006Pe-JJ for bug-gnu-emacs@gnu.org; Fri, 09 Aug 2024 15:06:14 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1723230365; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=ubxdUmXT/6R4mG6l3jH2BEmnhr/PE/ysfitrvT84VTw=; b=EjTM2cpiNACj+KzyVWsG6ncoyGRrQg5vGZa+Y3MDjuTsvhff6QoS1Azhzsgz5fcKdibwnl 9JTjmoHjagcCL/nRguFIUxi0OZYFuix0ZBCAA9qAwXB4JB8CE4vhERWLpnR1VbInkBrGDv LONLuwcAglRCibWJaKGeL+yanQpxG2G1PWCVkiEvg3aNpQFynJlbWh+dsGUGeAaJ0/kd2Z eSiYUj79eGFxtfnwmdt9OdloFQZg/uguxeqUF7y6A9rnT6YfxQaGPtLcM73qaN6CSu/wCz nxzo8PsnYmoCyKXo8rLtQtzNvu2TtjMh5Bcl/N1IRjp7tn9njIEvRHwoLhArKQ== X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=95.215.58.180; envelope-from=jb@jeremybryant.net; helo=out-180.mta1.migadu.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:289976 Archived-At: --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Fix-trivial-typos-in-comments-checkdoc-fixes-and-hea.patch >From 5cea8fbac339e434e2e246c0101599abd2b17779 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant 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 . +;;; 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 --=-=-=--