Clarify doc of scan-lists.

* doc/lispref/syntax.texi (Motion via Parsing): Doc fix for scan-lists.

* src/syntax.c (Fscan_lists): Doc fix.

Fixes: debbugs:10833

1 files changed, 13 insertions, 8 deletions

diff --git a/src/syntax.c b/src/syntax.c
index bb473a52b3a..645a65f13e6 100644
--- a/src/syntax.c
+++ b/src/syntax.c
@@ -2844,18 +2844,23 @@ scan_lists (register EMACS_INT from, EMACS_INT count, EMACS_INT depth, int sexpf
 
 DEFUN ("scan-lists", Fscan_lists, Sscan_lists, 3, 3, 0,
        doc: /* Scan from character number FROM by COUNT lists.
-Returns the character number of the position thus found.
+Scan forward if COUNT is positive, backward if COUNT is negative.
+Return the character number of the position thus found.
+
+A \"list", in this context, refers to a balanced parenthetical
+grouping, as determined by the syntax table.
 
-If DEPTH is nonzero, paren depth begins counting from that value,
-only places where the depth in parentheses becomes zero
-are candidates for stopping; COUNT such places are counted.
-Thus, a positive value for DEPTH means go out levels.
+If DEPTH is nonzero, treat that as the nesting depth of the starting
+point (i.e. the starting point is DEPTH parentheses deep).  This
+function scans over parentheses until the depth goes to zero COUNT
+times.  Hence, positive DEPTH moves out that number of levels of
+paretheses, while negative DEPTH moves to a deeper level.
 
 Comments are ignored if `parse-sexp-ignore-comments' is non-nil.
 
-If the beginning or end of (the accessible part of) the buffer is reached
-and the depth is wrong, an error is signaled.
-If the depth is right but the count is not used up, nil is returned.  */)
+If we reach the beginning or end of the accessible part of the buffer
+before we have scanned over COUNT lists, return nil if the depth at
+that point is zero, and signal a error if the depth is nonzero.  */)
   (Lisp_Object from, Lisp_Object count, Lisp_Object depth)
 {
   CHECK_NUMBER (from);