master 5769a105308: ; Fix doc strings of some treesit-related functions

[Eli Zaretskii]

branch: master
commit 5769a1053087a278d48836e1f366e0bd87c95809
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Fix doc strings of some treesit-related functions
    
    * lisp/treesit.el (treesit-defun-tactic)
    (treesit-defun-name-function, treesit-thing-at-point)
    (treesit-defun-at-point):
    * lisp/progmodes/c-ts-common.el (c-ts-common-statement-offset):
    * lisp/progmodes/c-ts-mode.el (c-ts-mode-toggle-comment-style)
    (c-ts-mode-indent-style, c-ts-mode-emacs-sources-support)
    (c-ts-mode--syntax-propertize, c-ts-mode--anchor-prev-sibling)
    (c-ts-mode--standalone-parent-skip-preproc)
    (c-ts-mode--standalone-grandparent, c-ts-mode--else-heuristic)
    (c-ts-mode--declarator-identifier)
    (c-ts-mode--fontify-declarator, c-ts-mode--fontify-variable)
    (c-ts-mode--defun-valid-p)
    (c-ts-mode--defun-for-class-in-imenu-p)
    (c-ts-mode--defun-skipper, c-ts-mode--emacs-defun-p)
    (c-ts-mode--emacs-defun-at-point)
    (c-ts-mode--emacs-current-defun-name, c-ts-mode--reverse-ranges)
    (c-ts-mode, c++-ts-mode, c-or-c++-ts-mode): Doc fixes.
---
 lisp/progmodes/c-ts-common.el |  2 +-
 lisp/progmodes/c-ts-mode.el   | 64 ++++++++++++++++++++++---------------------
 lisp/treesit.el               | 21 +++++++-------
 3 files changed, 44 insertions(+), 43 deletions(-)

diff --git a/lisp/progmodes/c-ts-common.el b/lisp/progmodes/c-ts-common.el
index 0095d83e302..e48bcc64f14 100644
--- a/lisp/progmodes/c-ts-common.el
+++ b/lisp/progmodes/c-ts-common.el
@@ -332,7 +332,7 @@ Assumes the anchor is (point-min), i.e., the 0th column.
 This function basically counts the number of block nodes (i.e.,
 brackets) (see `c-ts-common-indent-type-regexp-alist')
 between NODE and the root node (not counting NODE itself), and
-multiply that by `c-ts-common-indent-offset'.
+multiplies that by `c-ts-common-indent-offset'.
 
 To support GNU style, on each block level, this function also
 checks whether the opening bracket { is on its own line, if so,
diff --git a/lisp/progmodes/c-ts-mode.el b/lisp/progmodes/c-ts-mode.el
index 8383979a373..3a89f0f494b 100644
--- a/lisp/progmodes/c-ts-mode.el
+++ b/lisp/progmodes/c-ts-mode.el
@@ -97,7 +97,7 @@
   "Toggle the comment style between block and line comments.
 Optional numeric ARG, if supplied, switches to block comment
 style when positive, to line comment style when negative, and
-just toggles it when zero or left out."
+just toggles it when zero or omitted."
   (interactive "P")
   (let ((prevstate-line (string= comment-start "// ")))
     (when (or (not arg)
@@ -147,9 +147,9 @@ symbol."
   "Style used for indentation.
 
 The selected style could be one of GNU, K&R, LINUX or BSD.  If
-one of the supplied styles doesn't suffice, a function could be
-set instead.  This function is expected to return a list that
-follows the form of `treesit-simple-indent-rules'."
+one of the supplied styles doesn't suffice, the value could be
+a function instead.  This function is expected to return a list
+that follows the form of `treesit-simple-indent-rules'."
   :version "29.1"
   :type '(choice (symbol :tag "Gnu" gnu)
                  (symbol :tag "K&R" k&r)
@@ -202,8 +202,8 @@ To set the default indent style globally, use
             (if (derived-mode-p 'c-ts-mode) 'c 'cpp))))))
 
 (defcustom c-ts-mode-emacs-sources-support t
-  "Whether to enable Emacs source-specific features.
-This enables detection of definitions of Lisp function using
+  "Whether to enable Emacs source-specific C features.
+This enables detection of definitions of Lisp functions via
 the DEFUN macro.
 This needs to be set before enabling `c-ts-mode'; if you change
 the value after enabling `c-ts-mode', toggle the mode off and on
@@ -243,7 +243,7 @@ again."
 < and > are usually punctuation, e.g., in ->.  But when used for
 templates, they should be considered pairs.
 
-This function checks for < and > in the changed RANGES and apply
+This function checks for < and > in the changed RANGES and applies
 appropriate text property to alter the syntax of template
 delimiters < and >'s."
   (goto-char beg)
@@ -284,9 +284,9 @@ is actually the parent of point at the moment of 
indentation."
   "Return the start of the previous named sibling of NODE.
 
 This anchor handles the special case where the previous sibling
-is a labeled_statement, in that case, return the child of the
+is a labeled_statement; in that case, return the child of the
 labeled statement instead.  (Actually, recursively go down until
-the node isn't a labeled_statement.)  Eg,
+the node isn't a labeled_statement.)  E.g.,
 
 label:
   int x = 1;
@@ -295,10 +295,11 @@ label:
 The anchor of \"int y = 2;\" should be \"int x = 1;\" rather than
 the labeled_statement.
 
-Return nil if a) there is no prev-sibling, or 2) prev-sibling
+Return nil if a) there is no prev-sibling, or b) prev-sibling
 doesn't have a child.
 
-PARENT and BOL are like other anchor functions."
+PARENT is NODE's parent, BOL is the beginning of non-whitespace
+characters of the current line."
   (when-let ((prev-sibling
               (or (treesit-node-prev-sibling node t)
                   (treesit-node-prev-sibling
@@ -336,7 +337,7 @@ PARENT and BOL are like other anchor functions."
 
 (defun c-ts-mode--standalone-parent-skip-preproc (_n parent &rest _)
   "Like the standalone-parent anchor but skips preproc nodes.
-PARENT is the same as other anchor functions."
+PARENT is the parent of the current node."
   (save-excursion
     (treesit-node-start
      (treesit-parent-until
@@ -353,13 +354,15 @@ PARENT is the same as other anchor functions."
 
 (defun c-ts-mode--standalone-grandparent (_node parent bol &rest args)
   "Like the standalone-parent anchor but pass it the grandparent.
-PARENT, BOL, ARGS are the same as other anchor functions."
+PARENT is NODE's parent, BOL is the beginning of non-whitespace
+characters of the current line."
   (apply (alist-get 'standalone-parent treesit-simple-indent-presets)
          parent (treesit-node-parent parent) bol args))
 
 (defun c-ts-mode--else-heuristic (node parent bol &rest _)
   "Heuristic matcher for when \"else\" is followed by a closing bracket.
-NODE, PARENT, and BOL are the same as in other matchers."
+PARENT is NODE's parent, BOL is the beginning of non-whitespace
+characters of the current line."
   (and (null node)
        (save-excursion
          (forward-line -1)
@@ -757,7 +760,7 @@ MODE is either `c' or `cpp'."
 (defun c-ts-mode--declarator-identifier (node &optional qualified)
   "Return the identifier of the declarator node NODE.
 
-If QUALIFIED is non-nil, include the names space part of the
+If QUALIFIED is non-nil, include the namespace part of the
 identifier and return a qualified_identifier."
   (pcase (treesit-node-type node)
     ;; Recurse.
@@ -782,7 +785,7 @@ identifier and return a qualified_identifier."
      node)))
 
 (defun c-ts-mode--fontify-declarator (node override start end &rest _args)
-  "Fontify a declarator (whatever under the \"declarator\" field).
+  "Fontify a declarator (whatever is under the \"declarator\" field).
 For NODE, OVERRIDE, START, END, and ARGS, see
 `treesit-font-lock-rules'."
   (let* ((identifier (c-ts-mode--declarator-identifier node))
@@ -817,7 +820,7 @@ For NODE, OVERRIDE, START, END, and ARGS, see
 
 (defun c-ts-mode--fontify-variable (node override start end &rest _)
   "Fontify an identifier node if it is a variable.
-Don't fontify if it is a function identifier.  For NODE,
+Don't fontify it if it is a function identifier.  For NODE,
 OVERRIDE, START, END, and ARGS, see `treesit-font-lock-rules'."
   (when (not (equal (treesit-node-type
                      (treesit-node-parent node))
@@ -938,7 +941,7 @@ Return nil if NODE is not a defun node or doesn't have a 
name."
 
 (defun c-ts-mode--defun-valid-p (node)
   "Return non-nil if NODE is a valid defun node.
-Ie, NODE is not nested."
+That is, NODE is not nested."
   (let ((top-level-p (lambda (node)
                        (not (treesit-node-top-level
                              node (rx (or "function_definition"
@@ -977,8 +980,7 @@ Basically, if NODE is a class, return non-nil; if NODE is a
 function but is under a class, return non-nil; if NODE is a
 top-level function, return nil.
 
-This is for the Class subindex in
-`treesit-simple-imenu-settings'."
+This is for the Class subindex in `treesit-simple-imenu-settings'."
   (pcase (treesit-node-type node)
     ;; The Class subindex only has class_specifier and
     ;; function_definition.
@@ -989,7 +991,7 @@ This is for the Class subindex in
 
 (defun c-ts-mode--defun-skipper ()
   "Custom defun skipper for `c-ts-mode' and friends.
-Structs in C ends with a semicolon, but the semicolon is not
+Structs in C end with a semicolon, but the semicolon is not
 considered part of the struct node, so point would stop before
 the semicolon.  This function skips the semicolon."
   (when (looking-at (rx (* (or " " "\t")) ";"))
@@ -1009,7 +1011,7 @@ the semicolon.  This function skips the semicolon."
     (list node parent bol)))
 
 (defun c-ts-mode--emacs-defun-p (node)
-  "Return non-nil if NODE is a Lisp function defined using DEFUN.
+  "Return non-nil if NODE is a Lisp function defined via DEFUN.
 This function detects Lisp primitives defined in Emacs source
 files using the DEFUN macro."
   (and (equal (treesit-node-type node) "expression_statement")
@@ -1030,15 +1032,15 @@ files using the DEFUN macro."
   "Return the defun node at point.
 
 In addition to regular C functions, this function recognizes
-definitions of Lisp primitrives in Emacs source files using DEFUN,
-if `c-ts-mode-emacs-sources-support' is non-nil.
+definitions of Lisp primitrives in Emacs source files defined
+via DEFUN, if `c-ts-mode-emacs-sources-support' is non-nil.
 
 Note that DEFUN is parsed by tree-sitter as two separate
 nodes, one for the declaration and one for the body; this
 function returns the declaration node.
 
 If RANGE is non-nil, return (BEG . END) where BEG end END
-encloses the whole defun.  This is for when the entire defun
+enclose the whole defun.  This is for when the entire defun
 is required, not just the declaration part for DEFUN."
   (when-let* ((node (treesit-defun-at-point))
               (defun-range (cons (treesit-node-start node)
@@ -1067,7 +1069,7 @@ is required, not just the declaration part for DEFUN."
   "Return the name of the current defun.
 This is used for `add-log-current-defun-function'.
 In addition to regular C functions, this function also recognizes
-Emacs primitives defined using DEFUN in Emacs sources,
+Emacs primitives defined via DEFUN in Emacs sources,
 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))))
@@ -1145,7 +1147,7 @@ For BOL see `treesit-simple-indent-rules'."
 
 (defun c-ts-mode--reverse-ranges (ranges beg end)
   "Reverse RANGES and return the new ranges between BEG and END.
-Positions that were included RANGES are not in the returned
+Positions that were included in RANGES are not in the returned
 ranges, and vice versa.
 
 Return nil if RANGES is nil.  This way, passing the returned
@@ -1287,7 +1289,7 @@ BEG and END are described in `treesit-range-rules'."
 
 This mode is independent from the classic cc-mode.el based
 `c-mode', so configuration variables of that mode, like
-`c-basic-offset', doesn't affect this mode.
+`c-basic-offset', don't affect this mode.
 
 To use tree-sitter C/C++ modes by default, evaluate
 
@@ -1296,7 +1298,7 @@ To use tree-sitter C/C++ modes by default, evaluate
     (add-to-list \\='major-mode-remap-alist
                  \\='(c-or-c++-mode . c-or-c++-ts-mode))
 
-in your configuration."
+in your init files."
   :group 'c
   :after-hook (c-ts-mode-set-modeline)
 
@@ -1348,7 +1350,7 @@ To use tree-sitter C/C++ modes by default, evaluate
     (add-to-list \\='major-mode-remap-alist
                  \\='(c-or-c++-mode . c-or-c++-ts-mode))
 
-in your configuration.
+in your init files.
 
 Since this mode uses a parser, unbalanced brackets might cause
 some breakage in indentation/fontification.  Therefore, it's
@@ -1443,7 +1445,7 @@ matching on file name insufficient for detecting major 
mode that
 should be used.
 
 This function attempts to use file contents to determine whether
-the code is C or C++ and based on that chooses whether to enable
+the code is C or C++, and based on that chooses whether to enable
 `c-ts-mode' or `c++-ts-mode'."
   (declare (obsolete c-or-c++-mode "30.1"))
   (interactive)
diff --git a/lisp/treesit.el b/lisp/treesit.el
index fa82ad898a9..2b4893e6129 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -2237,7 +2237,7 @@ for invalid node.
 This is used by `treesit-beginning-of-defun' and friends.")
 
 (defvar-local treesit-defun-tactic 'nested
-  "Determines how does Emacs treat nested defuns.
+  "Determines how Emacs treats nested defuns.
 If the value is `top-level', Emacs only moves across top-level
 defuns, if the value is `nested', Emacs recognizes nested defuns.")
 
@@ -2253,9 +2253,8 @@ If the value is nil, no skipping is performed.")
 (defvar-local treesit-defun-name-function nil
   "A function that is called with a node and returns its defun name or nil.
 If the node is a defun node, return the defun name, e.g., the
-function name of a function.  If the node is not a defun node, or
-the defun node doesn't have a name, or the node is nil, return
-nil.")
+name of a function.  If the node is not a defun node, or the
+defun node doesn't have a name, or the node is nil, return nil.")
 
 (defvar-local treesit-add-log-defun-delimiter "."
   "The delimiter used to connect several defun names.
@@ -2728,12 +2727,12 @@ function is called recursively."
 
 ;; TODO: In corporate into thing-at-point.
 (defun treesit-thing-at-point (thing tactic)
-  "Return the THING at point or nil if none is found.
+  "Return the THING at point, or nil if none is found.
 
-THING can be a symbol, regexp, a predicate function, and more,
+THING can be a symbol, a regexp, a predicate function, and more;
 see `treesit-thing-settings' for details.
 
-Return the top-level THING if TACTIC is `top-level', return the
+Return the top-level THING if TACTIC is `top-level'; return the
 smallest enclosing THING as POS if TACTIC is `nested'."
 
   (let ((node (treesit--thing-at (point) thing)))
@@ -2742,11 +2741,11 @@ smallest enclosing THING as POS if TACTIC is `nested'."
       node)))
 
 (defun treesit-defun-at-point ()
-  "Return the defun node at point or nil if none is found.
+  "Return the defun node at point, or nil if none is found.
 
-Respects `treesit-defun-tactic': return the top-level defun if it
-is `top-level', return the immediate parent defun if it is
-`nested'.
+Respects `treesit-defun-tactic': returns the top-level defun if it
+is `top-level', otherwise return the immediate parent defun if it
+is `nested'.
 
 Return nil if `treesit-defun-type-regexp' isn't set and `defun'
 isn't defined in `treesit-thing-settings'."