[Laszlo-dev] For Review: Change 20070102-jgrandyw-x Summary: Bring new refguide over to branches/legals from private working branch

[P T Withington]

On 2007-01-04, at 11:55 EST, Jim Grandy wrote:

> Semi-intentional. I think the eventual goal is to use the @todo  
> format in a consistent way that is easy to parse. This would  
> actually argue for the following format, to be consistent with @param:
>
>> +  * @todo 2004-3-29 hqm: lines seem to get the ends clipped off  
>> if you use the TextField.textWidth
>
> But I hadn't gotten that far :-) Basically, if a TODO was within a  
> larger comment block that was getting reformatted anyway, I redid  
> it minimally so it would parse as a structured comment field. There  
> would be some advantage to using @todo everywhere, since then it  
> would be extractable using js2doc. We'll need to make a separate  
> pass through at some point if we want to normalize everything and  
> make that happen.

Ok, this is fine. I was thrown off by the mixed state of things.   
(And I need to update my font-lock customizations to find new-style  
todo's.)

The old format was:

('TODO'|'FIXME'|'NOTE') '['<iso-date>' '<email>']' ['('<bug- 
number')'] <text>

If we can make it so the doc tools can parse out the date/email and  
optional bug-number, that would be great.