bug#10833: 24.0.93; Docstring of `scan-lists'

bug#10833: 24.0.93; Docstring of `scan-lists'

[Michael Heerdegen]

Hello,

1. The docstring of `scan-lists' needs to explain what "scanning" means.
Currently, only looking at the docstring, if you not already know what
this function does, you'll also not know it after reading.

Something like this from the manual should be better:

     This function scans forward COUNT balanced parenthetical groupings
     from position FROM.

2. This sentence is strange:

"If the beginning or end of (the accessible part of) the buffer is reached
and the depth is wrong, an error is signaled."

What does "the depth is wrong" mean?  (I guess it's meant "the depth
is not zero", at least the manual says that.)

3. See #10659 - Did you also adopt the docstring of `scan-lists'?


Michael.



In GNU Emacs 24.0.93.1 (i486-pc-linux-gnu, GTK+ Version 3.2.3)
 of 2012-02-16 on zelenka, modified by Debian
 (emacs-snapshot package, version 2:20120216-1)
Windowing system distributor `The X.Org Foundation', version 11.0.11103901
Configured using:
 `configure '--build' 'i486-linux-gnu' '--host' 'i486-linux-gnu'
 '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib'
 '--localstatedir=/var' '--infodir=/usr/share/info'
 '--mandir=/usr/share/man' '--with-pop=yes'
 '--enable-locallisppath=/etc/emacs-snapshot:/etc/emacs:/usr/local/share/emacs/24.0.93/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.0.93/site-lisp:/usr/share/emacs/site-lisp'
 '--without-compress-info' '--with-crt-dir=/usr/lib/i386-linux-gnu/'
 '--with-x=yes' '--with-x-toolkit=gtk3' '--with-imagemagick=yes'
 'build_alias=i486-linux-gnu' 'host_alias=i486-linux-gnu'
 'CFLAGS=-DDEBIAN -DSITELOAD_PURESIZE_EXTRA=5000 -g -O2''

bug#10833: 24.0.93; Docstring of `scan-lists'

[Chong Yidong]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> 1. The docstring of `scan-lists' needs to explain what "scanning" means.
>
> 2. This sentence is strange:
>
> "If the beginning or end of (the accessible part of) the buffer is reached
> and the depth is wrong, an error is signaled."
>
> What does "the depth is wrong" mean?  (I guess it's meant "the depth
> is not zero", at least the manual says that.)
>
> 3. See #10659 - Did you also adopt the docstring of `scan-lists'?

I've edited the docstring and the manual to make it clearer what the
scanner actually does.  Thanks.