[SVN] r8757 (JavaScript JSDoc)

[Thomas Aylott - subtleGradient]

I'll have to think about my comments some more once i'm back at my  
computer.

Thomas Aylott [SubtleGradient] from iPhone

On Dec 31, 2007, at 5:42 AM, Michael Sheets <mummer at whitefalls.org>  
wrote:

> On Dec 31, 2007, at 4:41 AM, Michael Sheets wrote:
>
>> Adding review comments.
>
> # JavaScript JSDoc Bundle Comments
>
> Can we get a general show of hands on how widely used JSDoc is, and  
> if it's the only doc system for JavaScript? If it is we might want  
> to consider just moving this into the main JavaScript bundle?

I think there's another one. Someone will have to get a real answer  
though. Maybe ask around in all the js library IRC channels.

I would rather have the most widely used doc syntax included than make  
it very complex.

The trouble with not including the syntax is that nobody would use it  
except the 5 people that know about it and how to do it.

If each js library uses a different syntax then we can just override  
the doc syntax in the library grammar.

> * Unsure of tab trigger of /* might it be trigger by accident as  
> people align comments? Would /** change that, or is it not an issue?

Yeah good thinking. /** might be fine.

> * The "Comment" snippet seems misnamed, it should be Doc Comment or  
> similar. Or seeing as we have a block comment shortcut (⌘⌥/) we  
> could either make it that a second press of the shortcut would conve 
> rt the current comment block into a doc comment block, or make a sec 
> ond shortcut.

I'd like to keep the comment toggle on and off only. A 3 state toggle  
doesn't sound fun. But that might actually be the best option since  
it's a known shortcut.

> * Could move away from using CocoaDialog in favor of tm_dialog.

> * Could add a new rule to the JavaScript grammar to give doc blocks  
> their own scope to make the snippets more narrowly focused.

Agreed.