From d3ca0b3aa2ecdac799d6ef7dd50f613cb032d8e0 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 28 Apr 2023 08:40:56 +0300
Subject: [PATCH] ; * lisp/progmodes/c-ts-mode.el: Fix comments and doc strings
 (bug#62951).

---
 lisp/progmodes/c-ts-mode.el | 33 +++++++++++++++++----------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/lisp/progmodes/c-ts-mode.el b/lisp/progmodes/c-ts-mode.el
index 8f7a0f26b44..7a1ee66cb77 100644
--- a/lisp/progmodes/c-ts-mode.el
+++ b/lisp/progmodes/c-ts-mode.el
@@ -971,24 +971,25 @@ if `c-ts-mode-emacs-sources-support' is non-nil."
   (or (treesit-add-log-current-defun)
       (c-ts-mode--defun-name (c-ts-mode--emacs-defun-at-point))))
 
-;;; FOR_EACH_TAIL fix
+;;; Support for FOR_EACH_* macros
 ;;
-;; FOR_EACH_TAIL (and FOR_EACH_TAIL_SAFE) followed by a unbracketed
-;; body will mess up the parser, which parses the thing as a function
-;; declaration.  We "fix" it by adding a shadow parser, emacs-c (which
-;; is just c but under a different name).  We use emacs-c to find each
-;; FOR_EACH_TAIL with a unbracketed body, and set the ranges of the C
-;; parser so that it skips those FOR_EACH_TAIL's.  Note that we only
-;; ignore FOR_EACH_TAIL's with a unbracketed body.  Those with a
-;; bracketed body parses more or less fine.
+;; FOR_EACH_TAIL, FOR_EACH_TAIL_SAFE, FOR_EACH_FRAME etc., followed by
+;; an unbracketed body will mess up the parser, which parses the thing
+;; as a function declaration.  We "fix" it by adding a shadow parser
+;; for a language 'emacs-c' (which is just 'c' but under a different
+;; name).  We use 'emacs-c' to find each FOR_EACH_* macro with a
+;; unbracketed body, and set the ranges of the C parser so that it
+;; skips those FOR_EACH_*'s.  Note that we only ignore FOR_EACH_*'s
+;; with a unbracketed body.  Those with a bracketed body parse more
+;; or less fine.
 
 (defvar c-ts-mode--for-each-tail-regexp
   (rx "FOR_EACH_" (or "TAIL" "TAIL_SAFE" "ALIST_VALUE"
                       "LIVE_BUFFER" "FRAME"))
-  "A regexp matching all the FOR_EACH_TAIL variants.")
+  "A regexp matching all the variants of the FOR_EACH_* macro.")
 
 (defun c-ts-mode--for-each-tail-body-matcher (_n _p bol &rest _)
-  "A matcher that matches the first line after a FOR_EACH_TAIL.
+  "A matcher that matches the first line after a FOR_EACH_* macro.
 For BOL see `treesit-simple-indent-rules'."
   (when c-ts-mode-emacs-sources-support
     (save-excursion
@@ -1005,10 +1006,10 @@ For BOL see `treesit-simple-indent-rules'."
                 @for-each-tail)
                (:match ,c-ts-mode--for-each-tail-regexp
                        @_name))))
-  "Query that finds the FOR_EACH_TAIL with a unbracketed body.")
+  "Query that finds a FOR_EACH_* macro with an unbracketed body.")
 
 (defvar-local c-ts-mode--for-each-tail-ranges nil
-  "Ranges covering all the FOR_EACH_TAIL's in the buffer.")
+  "Ranges covering all the FOR_EACH_* macros in the buffer.")
 
 (defun c-ts-mode--reverse-ranges (ranges beg end)
   "Reverse RANGES and return the new ranges between BEG and END.
@@ -1031,7 +1032,7 @@ parser parse the whole buffer."
       (nreverse new-ranges))))
 
 (defun c-ts-mode--emacs-set-ranges (beg end)
-  "Set ranges for the C parser to skip some FOR_EACH_TAIL's.
+  "Set ranges for the C parser to skip some FOR_EACH_* macros.
 BEG and END are described in `treesit-range-rules'."
   (let* ((c-parser (treesit-parser-create 'c))
          (old-ranges c-ts-mode--for-each-tail-ranges)
@@ -1150,7 +1151,7 @@ in your configuration."
 
   (when (treesit-ready-p 'c)
     ;; Add a fake "emacs-c" language which is just C.  Used for
-    ;; skipping FOR_EACH_TAIL, see `c-ts-mode--emacs-set-ranges'.
+    ;; skipping FOR_EACH_* macros, see `c-ts-mode--emacs-set-ranges'.
     (setf (alist-get 'emacs-c treesit-load-name-override-list)
           '("libtree-sitter-c" "tree_sitter_c"))
     ;; If Emacs source support is enabled, make sure emacs-c parser is
@@ -1173,7 +1174,7 @@ in your configuration."
     (setq-local treesit-defun-tactic 'top-level)
     (treesit-major-mode-setup)
 
-    ;; Emacs source support: handle DEFUN and FOR_EACH_TAIL gracefully.
+    ;; Emacs source support: handle DEFUN and FOR_EACH_* gracefully.
     (when c-ts-mode-emacs-sources-support
       (setq-local add-log-current-defun-function
                   #'c-ts-mode--emacs-current-defun-name)
-- 
2.39.2