Re: master 305dbc7 2/4: Move description of value to syntax-ppss function.

[Noam Postavsky <npostavs@gmail.com>]

On Fri, 13 Dec 2019 at 08:03, Dmitry Gutov <dgutov@yandex.ru> wrote:

>> -  (innermost-start
>> +  (list-start
>
> Sounds ambiguous: the point is that it's innermost, among possible other
> list starts.

>> -  (last-complete-sexp-start
>> +  (last-sexp-start
>
> Same (but, like, in reverse): "complete" is important.

Not sure I agree, but I can live with the current names.

> > -  (comment-nesting nil :documentation "\
> > +  (comment nil :documentation "\
>
> Doesn't this name imply some other value? Like a string (comment opener
> or its contents)?

Hmm, you might be right about that. How about 'comment-depth': two
characters shorter, and the other names also use "depth" rather than
"nesting".

> > -  (comment-or-string-start
> > +  (context-start
> >      nil :documentation
> >      "character address of start of comment or string; nil if not in one.")
>
> That kind of implies that strings and comments are the most important
> contexts when parsing a file.

Yeah, I think was I looking at syntax-ppss-context when I originally
wrote this, but in that case there is an argument to tell what
"context" refers to, so I agree it doesn't really make sense here.

> > -  (open-paren-positions
> > +  (open-parens
> >      nil :documentation
> >      "List of positions of currently open parens, outermost first.")
> > -  (two-character-syntax nil :documentation "\
> > +  (syntax-sequence nil :documentation "\
> >   When the last position scanned holds the first character of a
> >   (potential) two character construct, the syntax of that position,
> >   otherwise nil.  That construct can be a two character comment
>
> These look okay to me.

I'm actually feeling that the two-character-syntax one should be left
as is, it's kind of obscure so having a longer and more explicit name
seems better.

> min-depth too, but, like last-complete-sexp-start, these fields in
> values returned by syntax-ppss are unreliable/undefined, so they won't
> be used in most Lisp programs anyway.

I might be biased by having worked on the lisp indentation code which
uses those fields quite a bit.