bug#8693: 24.0.50; doc strings in syntax.el

bug#8693: 24.0.50; doc strings in syntax.el

[Drew Adams]

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'
 

bug#8693: 24.0.50; doc strings in syntax.el

[Drew Adams]

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

bug#8693: 24.0.50; doc strings in syntax.el

[Stefan Monnier]

> 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

bug#8693: 24.0.50; doc strings in syntax.el

[Drew Adams]

> > 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.

bug#8693: 24.0.50; doc strings in syntax.el

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#8693: 24.0.50; doc strings in syntax.el

[Drew Adams]

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

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

bug#8693: 24.0.50; doc strings in syntax.el

[Lars Ingebrigtsen]

Lars Magne Ingebrigtsen <larsi@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

bug#8693: 24.0.50; doc strings in syntax.el

[Drew Adams]

> >> 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.