Friday, May 25, 2007

Ruby Screenshot of the Week #12: Improved Ruby Documentation

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.


One of the things I did this week was to rewrite the code which extracts documentation for all the core Ruby APIs (which are defined in the C Ruby implementation). This fixes some bugs where a method here and there were missing its documentation.



In doing so, I started looking at the actual IDE presentation of the documentation as well, and thought I could make it a lot more appealing. Without further ado, here's how the documentation looks now:






The most interesting part here is that the IDE now figures out whether portions of the documentation corresponds to Ruby code, and then presents it with syntax highlighting right there in the documentation popup. (I've also improved the way the method signatures are displayed so it should use less space and be more readable now, although that's harder to spot than if you compare before-and-after shots.)



Heres another example. This shows a migration in a Rails application, where you're getting code completion on the create_table method.






One interesting aspect of this highlighting is that it's easier to spot mistakes in your comments. As I was testing this feature, I pulled up the documentation on the Rails send_file method - and the following code fragment looked wrong:






Sure enough, it looks like it's missing a single-quote right after 404.html. This is the kind of thing which will be a lot easier to spot and fix with the new enhanced highlighting!



P.S. You don't have to use code completion to get the documentation popup - just hit Ctrl-Shift-Space with the caret on the symbol you want to look up - or Command-Shift-Space on the Mac.



(P.S.2: If you're trying to download this, see my other blog entry on the current temporary download location.)


14 comments:

  1. tor, been using the netbeans ruby plugin all week, and just moved to the special ruby ide build. good stuff.
    please take all this as positive in the big picture, because i am a fan of netbeans (used off and on for years) and definately appreciate the work you guys are doing for ruby...
    1. my attr_accessor|_reader|_writer 's symbol definitions are not picked up by the code completion. at least they are not picked up in a method def when i type @<ctrl-space>, i get no help. previously used or initialized instance variables do appear to be picked up. class variables (e.g. @@a='hello') do not appear to be picked up by code completion either.
    2. how are you prioritizing the code completion list. if i create two simple classes, A and B. on A i define 'test' method. now i go into B and create a method 'testA'. in there, i say "a = A.new". the next line i type a.<ctrl space>. i get a huge list. i the programmer have added one method to A. i would think that would appear at the top or would have some priority. i think a quick user study would reveal some better ordering algorithm. i also think fading would be helpful. i'd really like to see those kernel methods a very faint grey. there must be some way to enhance the signal to noise.
    3. Same two simple classes as above. on class def B, i define a B.test method that simple prints 'tested'. outside of class B, in my main.rb, i type B.<ctrl-space> i do not see the class method 'B.test' i have defined. i try B::<ctrl-space> and still do not see it.
    4. if i type require<space><ctrl-space>i get a very weird list of choices. it isn't until i type require '<ctrl-space> that i get the actual list of valid candidates. not a big deal, but you could pop the other list up and quote the choice for the user.
    are you interested in usability opinions? i have noticed quite a bit of inconsistencies in the general use of netbeans.

    ReplyDelete
  2. ugh.. your blog throws out whitespace..

    ReplyDelete
  3. Another milestone. Congrats, Tor!

    I have been filing issues to NBM issuezilla these days, so I won't litter your blog space. But please do look into those and if in-appropriate feel free to close them. Some of issues I filed were against wrong scripting engine i guess.

    ReplyDelete
  4. FYI - I've updated the build page (http://wiki.netbeans.org/wiki/view/RubyInstallation)
    with a link to a new build which has a workaround for the RHTML issue (and the OSX icon is corrected - I'll get to the other packaging stuff later.)

    ReplyDelete
  5. Nice! Glad to see the "Go to File" feature added. It does seem somewhat flakey though, the wildcarding usually doesn't work right. I have a controller called "amazon controller.rb". When I type "*controller" I get "no files found". I probably have 30 files that match that pattern. If don't use wildcards, it does seem to work correctly.
    Couple other thoughts. I'm a huge IntelliJ fan so there are some features I miss:
    1) Open Class (works like Go to File but for classes)
    2)duplicate line (ctrl -D in intellij) - it's really suprising how often dupe line comes in handy!
    3) IntelliJ's bookmarks are SO MUCH BETTER: CTRL-SHIFT-1 sets bookmark #1 at the current location, CTRL-1 goes there. CTRL-SHIFT-2 sets a second bookmark, CTRL-2 goes there. etc. This is great when you find yourself swtiching back and forth from several locaitons in the code (which I find is quite often)
    4) the comment functionality of eclipse and IJ are superior: ctrl slash toggles between commented/uncommented.
    You have surpassed IJ for Ruby support by quite a bit now though, that's why I'm using NetBeans now - at least for Ruby. Great work!

    ReplyDelete
  6. Thanks a lot for your job, Tor!! Just wanted to ask, is there a haml support in your task list? (with Go to Rails Action/View possibility) :) Great work!! thank s again.

    ReplyDelete
  7. My NBM issuezilla handle would be gnufied.

    ReplyDelete
  8. Tor, I found some nasty issues with plugin installation modules. Ability to install downloaded plugins is total broken with 1386.
    Please have a look at ticket # 105122

    ReplyDelete
  9. Hi, Tor! I've heard about FastRI - that is much faster and smarter than ri - may be it would be interesting for you http://eigenclass.org/hiki/fastri

    ReplyDelete
  10. Vladimir OleynikJune 3, 2007 at 10:52 PM

    ...some features I miss:
    1) Open Class (works like Go to File but for classes)
    2)duplicate line (ctrl -D in intellij)....

    1) look for "Go to type" plugin (hack for ruby mode). it does open classes.
    2) there is such function, and even better -- you can duplicate a line above the cursor line or beneath it. Look at Options->Keymap->Other to find what hotkeys you have and redefine it to ctrl+d, the functions called "Copy Selection else line up" and "Copy Selection else line down".
    And one more vote for "toggle comments" feature :)
    btw, if I ever mistakenly commented out a line twice and use 'uncomment' hotkey then, rubyide on win hugs :(

    ReplyDelete
  11. Vladimir OleynikJune 3, 2007 at 10:53 PM

    ...some features I miss:
    1) Open Class (works like Go to File but for classes)
    2)duplicate line (ctrl -D in intellij)....

    1) look for "Go to type" plugin (hack for ruby mode). it does open classes.
    2) there is such function, and even better -- you can duplicate a line above the cursor line or beneath it. Look at Options->Keymap->Other to find what hotkeys you have and redefine it to ctrl+d, the functions called "Copy Selection else line up" and "Copy Selection else line down".
    And one more vote for "toggle comments" feature :)
    btw, if I ever mistakenly commented out a line twice and use 'uncomment' hotkey then, rubyide on win hugs :(

    ReplyDelete
  12. Thanks, Vladimir! I've gone to Options->Keymap->Other, and set ctrl+shift+c for the Remove trailing spaces.. and after that i've done the macros - which reformats code and then removes trailing spaces - and gave it alt+space shorcut - it's amazing.. i more and more love this IDE :)

    ReplyDelete
  13. Vladimir OleynikJune 4, 2007 at 7:40 PM

    Tor,
    something worng with the blog's comments,
    when one posts a comment, it doesn't show, but the comment of the next user will shift the previous comment, so it shows, but with wrong author.

    ReplyDelete
  14. Vladimir OleynikJune 4, 2007 at 7:42 PM

    Oh, sorry, disregard my previous post :(

    ReplyDelete