Ruby Screenshot of the Week #19: Comment Reformatting

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, 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:


I love using the Netbeans hudson builds. Is the ruby only version of Netbeans going to be a separate product once Netbeans 6 is officially released? It progressed so much in the last year, its amazing. Keep up the great work.


Posted by Dan Baxter on September 26, 2007 at 01:42 PM PDT #

The current beta download site already has a Ruby only:

I would be lovely if Ctrl-Shift-P worked for conventional Java code as well, it's the same problem we have there (and the reformat does not touch on comments).

Posted by Casper on September 26, 2007 at 09:18 PM PDT #

Honestly I am continuously saying "wow" to myself with every "ruby screen shot" post.

Posted by Brian Ehmann on September 27, 2007 at 02:26 AM PDT #

yes, great work! :) and yet still waiting for HAML support ;)

Posted by ruby.freeman on September 27, 2007 at 09:12 AM PDT #

This is unbelievably fantastic. Not only does this same me a lot of futzing around to nicely format my comments by hand, but when I open up someone else's code with long comments, I don't have to scroll left-right-left-right to read the comments, I can just reformat them. Way to go!

Posted by Chris Kutler on September 27, 2007 at 11:58 AM PDT #

also, Tor - it would be great to add such things as soft word wrape (that is, to reformat only on the screen, not in the real code) for the ruby code as well as for comments, and "mach brace" and "select to brace" - as it's done in SciTE for example - I think it's very useful things. Thanks!

Posted by ruby.freeman on September 27, 2007 at 01:13 PM PDT #

sorry, "math brace" and "select to brace" are already implemented, I've just found them :)

Posted by ruby.freeman on September 27, 2007 at 01:16 PM PDT #

Hello Tor,
Do you plan on implementing 3rd Rail style Object Hierarhy browser (input/output)? Or is it there already in the beta?

Posted by Bharat Ruparel on September 28, 2007 at 06:49 AM PDT #

Amazing...keep it up.

Posted by Hemant Kumar on September 28, 2007 at 07:05 PM PDT #

Probably would be handy to integrate the rspec bundle:

It would certainly be good to keep the trunk stuck in the default code templates as it now has some Story Runner support.

Posted by ylon on September 29, 2007 at 09:26 AM PDT #

Tor, getting a couple of oddities it seems. First, it appears that NB is indexing projects each time I restart the ide. It is taking \*huge\* amounts of time to index a relatively small rails project. (ie, it's been running about 5 minutes and only at 10% indexing a project w/ svn). I've not seen this behavior on prior builds to today it seems.

Along with this it seems that when I typed in a code template and then tab'd to fill it, the entire IDE hung and I'm not seeing any msgs in the console.

Also, can a user turn on/off autotest functionality at will? I am getting a green block on in the upper right of the text editor which seems to indicate that my tests pass, however my Growl autotest indicator w/ terminal output is showing indeed that it should not be passing. Running rSpec with ZenTest.

Finally, I tried duplicating City Lights theme and then heavily modifying it and upon ide restart all theming is nil. It's pure black and white with no highlighting whatsoever.

Posted by ylon on September 29, 2007 at 11:15 AM PDT #

Tor, it appears that this "hanging" upon code template completion occurs when it it still attempting to index. Also, if you control-space it will hang on scanning, but not freeze up the app like code template completion does.

Posted by ylon on October 01, 2007 at 05:03 AM PDT #

(There's also a hidden mode you can enable such that it reflows the current paragraph automatically as you edit comments.)

Any hints about where this is hidden?

Posted by Dan Lynn on October 01, 2007 at 08:19 AM PDT #

Hi all, thank you for your comments!

Casper: Yes, when I get some time I will port this feature such that it works in Java files as well!

Ruby.freeman: Yes, I know we need to get softwrap - but it will have to be the next version :) I'm glad you found the match brace function - look at to see other useful and possibly hidden functionality...

Bharat: Sorry, there's no object hierarchy browser in this release. It's on the list for the updates though.

Ylon: I have already created an rspec optional module; it should be on the update center and has all the new (recently updated) TextMate snippets. It also provides an action for running the focused spec. The only reason I haven't merged it into the continuous Ruby build is that it appears the RSpec snippets are replacing rather than adding to the Ruby snippets; I've gotta investigate that first. (It's in CVS under ruby/rspec/).

Regarding your indexing bug: Yeah, that's a problem which happens occasionally; it's high on my list of bugs to fix over the next couple of weeks. Basically, indexing is done but the task exits without cleaning up the IDE-handle for task progress, so the progress bar sits there forever. Just restart the IDE and you should be good. If you can actually -reproduce- this reliably I would love more details.

The green block above the vertical scrollbar just tells you that the file has no errors (unrelated to tests; introduce a parse error and it turns red; put some warnings or code that produces quickfixes and it turns yellow). Autotest itself will display a red or yellow error summary in the editor footer - you can't miss it. (It doesn't print anything green since it runs all the time and would get distracting).

Thanks for the report on code completion hangs - I think this is the same as issue .

I'm not sure what's going on with the dark color theme editing - I've done some editing myself and it worked okay. However, there's a special module support for theme editing that Tim Boudreau has written which makes it a lot easier. I'll post something about it once the bits are available somewhere.

Dan, to turn on auto-formatting run NetBeans with -J-Druby.autowrap.comments=true (optionally add to the etc/nbrubyide.conf or etc/netbeans.conf files to make it "persistent". I haven't checked this feature in a while so there could be issues - if so, let me know.

Posted by Tor Norbye on October 02, 2007 at 01:56 AM PDT #

Thanks Tor, also who should be contacted regarding NB remembering its window size and position upon restart? I'm using it on a 30" monitor and it consumes my entire screen at each start which is pretty annoying... It is also rough on my laptop, etc. as I'd like to have it squeezed into a certain size and position each time.

Posted by ylon on October 03, 2007 at 12:59 AM PDT #

Tor, in terms of reproducing the issue, a good way to make things gag on a project is to `rake rails:freeze:edge` or use piston and do similarly. At first it seems as though its just because of the large number of files its indexing, but I'm not sure of that any more and thus my having reported it to you. Is there a way I can sample the app and see the output for the index process? It may just be working very hard, but many I have to walk away for probably about an hour, which is odd on my pretty quick machine (with RAID-0).

Posted by ylon on October 03, 2007 at 04:42 AM PDT #

Hi Freeman,
there's some early work on HAML and SASS support available now -- see the following entry from

...and get the bits to install here:

Please report any issues you have with it. You may want to restart the IDE after installing the plugin.

Posted by Tor Norbye on October 11, 2007 at 10:22 AM PDT #

Hi Tor!!
Thanks a lot for your concern!! I've started to test it, and it looks great!! Thanks again!!

Posted by ruby.freeman on October 11, 2007 at 11:16 AM PDT #

Post a Comment:
Comments are closed for this entry.

Tor Norbye


« July 2016