bug#24172: 25.1; Doc of parse-sexp-ignore-comments: what does a value of nil mean?

[Alan McKenzie]

Hello, Lars.

In article <mailman.2415.1564240928.2688.bug-gnu-emacs@gnu.org> you wrote:
> Michael Heerdegen <michael_heerdegen@web.de> writes:

>> in the docstring of `parse-sexp-ignore-comments' (or at least in the
>> manual), I miss a description about what a value of nil exactly means:
>> How are comments treated then?  Are they treated as separate units that
>> can then be parsed as well, but separately from code, or are they treated
>> as indistinguishable from code?

>> For example, if parsing starts from within a comment, and parsing finds
>> the end of the comment and is not yet finished, is parsing just
>> continued inside the following code, or does it fail?

> After doing some testing, it seems that if it's nil, the commands
> affected by the setting just treat the commented-out text as if it
> wasn't commented out.

> So the answer to your last question seems to be "yes".

> ;; (foo

> (bar zot))

> However, pretty much the same thing happens with a non-nil value, too --
> with point before (foo C-M-f will advance past zot)).

> So it doesn't treat comments as whitespace, really -- it only does that
> if point is outside (before, at the end of a line, etc) the comment to
> begin with.  Seems like you could write an essay about it, but perhaps
> it's not worth listing the eccentricities here which I guess could change.

parse-sexp-ignore-comments (or, rather, parse_sexp_ignore_comments) is
tested, and acted upon, by precisely one C function, scan_lists in
syntax.c.  scan_lists is used by just two primitives, scan-lists and
scan-sexps.  These, in turn, are called by forward-list, etc.

When this variable is nil, scan_lists fails to recognise comment
delimiters - it just goes past them as though they were random
punctuation characters.  By contrast, when parse-sexp-ignore-comments is
t, scan_lists calls a comment scanning function when it encounters a
comment delimiter.

Noteworthy is that parse-partial-sexp doesn't respect the setting of
parse-sexp-ignore-comments.  This might be considered a bug.

All in all, this variable seems not to be a good idea.  It is not tested
consistently by the syntax routines (see above), must be set explicitly
to t by any major mode with comments, the nil value is rarely used, and
it is not clear whether this nil value is actually ever useful.

It would seem that if a major mode does not want comments to be
recognised, it would be better not to give any character comment syntax
in its syntax table.

> -- 
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no

-- 
Alan Mackenzie (Nuremberg, Germany).