GNU bug report logs - #60531
29.0.50; Some fixes and suggestions for the docstrings of treesit-parent-while and treesit-parent-until

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 60531 in the body.
You can then email your comments to 60531 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Daniel Martín <mardani29 <at> yahoo.es>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; Some fixes and suggestions for the docstrings of
 treesit-parent-while and treesit-parent-until
Date: Tue, 03 Jan 2023 23:45:35 +0100

The docstring of treesit-parent-while says:

Return the furthest parent of NODE that satisfies PRED.
Return nil if none was found.  PRED should be a function that
takes one argument, the parent node.

But, according to the source code, the first invocation of NODE passes
NODE itself, not its parent:

(let ((last nil))
    (while (and node (funcall pred node))

The same happens with the docstring of treesit-parent-until.

Another suggestion I have is that "the furthest parent of NODE" is a bit
ambiguous (furthest from NODE or from the root?).  I think it would be
more clear to say it will return the highest (ie. least deep) *ancestor*
of NODE.  In 37.3 Retrieving Nodes, we introduce the concepts of
"higher" and "lower" when explaining Tree-sitter nodes, so using this
terminology consistently would avoid confusion.

Message #10 received at 60531-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Martín <mardani29 <at> yahoo.es>
Cc: 60531-done <at> debbugs.gnu.org
Subject: Re: bug#60531: 29.0.50;
 Some fixes and suggestions for the docstrings of treesit-parent-while
 and treesit-parent-until
Date: Thu, 05 Jan 2023 09:35:17 +0200

> Date: Tue, 03 Jan 2023 23:45:35 +0100
> From:  Daniel Martín via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> 
> The docstring of treesit-parent-while says:
> 
> Return the furthest parent of NODE that satisfies PRED.
> Return nil if none was found.  PRED should be a function that
> takes one argument, the parent node.
> 
> But, according to the source code, the first invocation of NODE passes
> NODE itself, not its parent:
> 
> (let ((last nil))
>     (while (and node (funcall pred node))
> 
> The same happens with the docstring of treesit-parent-until.

This is clearly a case of unnecessary details.  I made the doc string
say just "node".

> Another suggestion I have is that "the furthest parent of NODE" is a bit
> ambiguous (furthest from NODE or from the root?).  I think it would be
> more clear to say it will return the highest (ie. least deep) *ancestor*
> of NODE.  In 37.3 Retrieving Nodes, we introduce the concepts of
> "higher" and "lower" when explaining Tree-sitter nodes, so using this
> terminology consistently would avoid confusion.

Instead of changing a potentially confusing word to another
potentially confusing word, I decided to describe in more detail what
the functions do.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.