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

[Lars Ingebrigtsen <larsi@gnus.org>]

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