GNU bug report logs - #8693
24.0.50; doc strings in syntax.el

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 8693 in the body.
You can then email your comments to 8693 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: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc strings in syntax.el
Date: Wed, 18 May 2011 09:14:50 -0700

1. Everywhere in syntax.el, please change "upto" to "up to".
(Not English.)
 
2. In doc strings of `syntax-propertize-function' and
`syntax-propertize-extend-region-functions': Please describe
START and END: their meanings and possible values (type).
Likewise NEW-START and NEW-END.
 
3. IN doc string of `syntax-propertize-rules':
"if SYNTAX has the form (prog1 EXP . EXPS) then the value
 returned by EXP will be applied to the buffer before running
 EXPS and if EXP is a string it is also converted with
 `string-to-syntax'."
Need descriptions of what EXP and EXPs are: meanings and possible values
(types).
 
4. Doc string of `syntax-propertize-via-font-lock':
"Propertize for syntax in START..END using font-lock syntax..."
There are no parameters START, END.  Please describe them and
relate them to the function.
 
5. Doc string of `syntax-propertize': It would be clearer if POS were
described (e.g. as a buffer position).  Same thing elsewhere that the meaning
might not be obvious.  (Calling it POSITION would pretty much obviate the need
for a description.)
 
6. Doc string of `syntax-ppss-cache': Describe POS and PPSS.
 
7. Doc string of `syntax-ppss-last': Describe LAST-POS and LAST-PPSS.
 
8. Doc string of `syntax-ppss-flush-cache': Describe parameter IGNORED.
 
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-05-16 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/build/include'
 

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <8693 <at> debbugs.gnu.org>
Subject: RE: bug#8693: 24.0.50; doc strings in syntax.el
Date: Wed, 18 May 2011 09:28:17 -0700

9. Please add doc strings for var and fn `syntax-ppss-stats'.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8693 <at> debbugs.gnu.org
Subject: Re: bug#8693: 24.0.50; doc strings in syntax.el
Date: Wed, 18 May 2011 19:10:09 -0300

> 9. Please add doc strings for var and fn `syntax-ppss-stats'.

No, this one only requires an extra dash since it's an internal
debugging/profiling function.


        Stefan

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 8693 <at> debbugs.gnu.org
Subject: RE: bug#8693: 24.0.50; doc strings in syntax.el
Date: Wed, 18 May 2011 15:46:31 -0700

> > 9. Please add doc strings for var and fn `syntax-ppss-stats'.
> 
> No, this one only requires an extra dash since it's an internal
> debugging/profiling function.

Then please also add a comment to that effect (that it is used only for
debugging/profiling).  I tried to figure out from its apparent use what it was
about, and it wasn't clear to me.  A comment would have saved unnecessary
examination, if it is only for debugging/profiling.

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8693 <at> debbugs.gnu.org
Subject: Re: 24.0.50; doc strings in syntax.el
Date: Fri, 15 Jul 2011 15:53:21 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 1. Everywhere in syntax.el, please change "upto" to "up to".
> (Not English.)

Two instances fixed.

> 2. In doc strings of `syntax-propertize-function' and
> `syntax-propertize-extend-region-functions': Please describe
> START and END: their meanings and possible values (type).
> Likewise NEW-START and NEW-END.
>
> 3. IN doc string of `syntax-propertize-rules':
> "if SYNTAX has the form (prog1 EXP . EXPS) then the value
>  returned by EXP will be applied to the buffer before running
>  EXPS and if EXP is a string it is also converted with
>  `string-to-syntax'."
> Need descriptions of what EXP and EXPs are: meanings and possible values
> (types).
>
> 4. Doc string of `syntax-propertize-via-font-lock':
> "Propertize for syntax in START..END using font-lock syntax..."
> There are no parameters START, END.  Please describe them and
> relate them to the function.
>
> 5. Doc string of `syntax-propertize': It would be clearer if POS were
> described (e.g. as a buffer position).  Same thing elsewhere that the meaning
> might not be obvious.  (Calling it POSITION would pretty much obviate the need
> for a description.)
>
> 6. Doc string of `syntax-ppss-cache': Describe POS and PPSS.
>
> 7. Doc string of `syntax-ppss-last': Describe LAST-POS and LAST-PPSS.
>
> 8. Doc string of `syntax-ppss-flush-cache': Describe parameter IGNORED.

Do you have a suggestion for descriptions for these things?

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 8693 <at> debbugs.gnu.org
Subject: RE: 24.0.50; doc strings in syntax.el
Date: Fri, 15 Jul 2011 08:09:41 -0700

> Do you have a suggestion for descriptions for these things?

No.  I reported the bug because I would like descriptions.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8693 <at> debbugs.gnu.org
Subject: Re: bug#8693: 24.0.50; doc strings in syntax.el
Date: Thu, 28 Apr 2016 12:59:47 +0200

Lars Magne Ingebrigtsen <larsi <at> gnus.org> writes:

>> 2. In doc strings of `syntax-propertize-function' and
>> `syntax-propertize-extend-region-functions': Please describe
>> START and END: their meanings and possible values (type).
>> Likewise NEW-START and NEW-END.

This seems like it has been fixed...

>> 3. IN doc string of `syntax-propertize-rules':
>> "if SYNTAX has the form (prog1 EXP . EXPS) then the value
>>  returned by EXP will be applied to the buffer before running
>>  EXPS and if EXP is a string it is also converted with
>>  `string-to-syntax'."
>> Need descriptions of what EXP and EXPs are: meanings and possible values
>> (types).

I think the natural interpretation here is that EXP is of the same type
as SYNTAX otherwise described.  (And EXPS is a list of whatever that is.)

>> 4. Doc string of `syntax-propertize-via-font-lock':
>> "Propertize for syntax in START..END using font-lock syntax..."
>> There are no parameters START, END.  Please describe them and
>> relate them to the function.

Fixed.

>> 5. Doc string of `syntax-propertize': It would be clearer if POS were
>> described (e.g. as a buffer position).  Same thing elsewhere that the meaning
>> might not be obvious.  (Calling it POSITION would pretty much obviate the need
>> for a description.)

I've clarified.

>> 6. Doc string of `syntax-ppss-cache': Describe POS and PPSS.
>>
>> 7. Doc string of `syntax-ppss-last': Describe LAST-POS and LAST-PPSS.

Seems unnecessary for these internal things.

>> 8. Doc string of `syntax-ppss-flush-cache': Describe parameter
>> IGNORED.

It's...  ignored.

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 8693 <at> debbugs.gnu.org
Subject: RE: bug#8693: 24.0.50; doc strings in syntax.el
Date: Thu, 28 Apr 2016 06:55:14 -0700 (PDT)

> >> Need descriptions of what EXP and EXPs are: meanings and possible
> >> values (types).
> 
> I think the natural interpretation here is that EXP is of the same type
> as SYNTAX otherwise described.  (And EXPS is a list of whatever that is.)

There is no "natural interpretation".  Such things need to be
specified.  If Emacs Dev knows what the meaning/behavior is
then it should specify it.  If it does not know then it should
not expect users to guess.

> >> 6. Doc string of `syntax-ppss-cache': Describe POS and PPSS.
> >> 7. Doc string of `syntax-ppss-last': Describe LAST-POS and LAST-PPSS.
> 
> Seems unnecessary for these internal things.

They are not internal.  Programmers who use these functions
deserve to know what their parameters are.  This is why we
have doc strings.

Previous Next

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