WARNING: This blog entry was imported from my old blog on blogs.sun.com (which used different blogging software), so formatting and links may not be correct.
I've been working on beefing up the RHTML support this week, but since I'm not done yet I'll talk about that next week. Instead I'll show you a feature that's actually in beta1, but you may not be aware of.
Let's say you have this code:
Have you ever wondered what the vertical faint red line on the right hand side of the editor is? It's the soft text limit line. It's telling you that beyond this line, you're going over 80 characters. There's nothing magical about 80 - you can configure it to something else, as I have done here, but more on that later.
Anyway, this comment is obviously not pretty since I've pasted in some text with long lines. This happens to my comments all the time after I edit them, removing a sentence here or adding another there.
But let's get to the point. Place the caret somewhere in the comment (as I have done). Now press Ctrl-Shift-P (on OSX, Command-Shift-P). Voila - the paragraph gets reformatted:
Notice that the IDE understands RDoc conventions. It has left preformatted code alone, and has recognized the numbered list and has formatted it appropriately. (There's also a hidden mode you can enable such that it reflows the current paragraph automatically as you edit comments.)
You can configure the text limit line in the general editor options - it's called "right margin":
One other interesting thing you can do with comments is view how RDoc will format them. Just use the normal "show documentation" gesture (Ctrl-Shift-Space, or Command-Shift-Space, to show the documentation for the symbol under the caret). This normally shows the documentation for a class or method that your caret is pointing to, but inside a comment, this will show the comment itself rendered rdocily:
That can be handy to check your docs as you're editing them (although this wasn't working properly in beta1, so get a daily build). The above example doesn't contain a lot of interesting rdoc markup, but let's say you brought this up on for example the form_tag method, you'd see something like this:
Notice how some of the code fragments are syntax highlighted as well - this is taking advantage of the enhanced rdoc rendering I've described earlier. And when tweaking your documentation, don't forget spell checking!
Finally, the above comment screenshots are a bit boring. Inline use of rdoc tags are also syntax highlighted. We were just discussing the meanings of the various colors on
dev@ruby.netbeans.org, and the following screenshot shows the meanings of the various syntactic constructs. Notice how rdoc tokens like :nodoc: and words surrounded by underscores are highlighted:
