That's some cool software. It would be cool is they applied their deep understanding of Ruby code to a code browser.
Often times to understand how a piece of Ruby code works it's not enough to just look at the source of that specific method. For example if I type in 'ActiveRecord.find', the second result is the one I want, ActiveRecord::FinderMethods.find, and I click it. The documentation is a bit long, so I click 'view source'. The code is short and sweet, but not very enlightening, it's just a wrapper around 'find_by_ids'.
Now luckily 'find_by_ids' is a public method so that's documented and I can search for it. But almost guaranteed at some point the code is going into private api's and I can't use the documentation anymore to understand it.
This is why I always have a local checkout of the Rails code and any other big gems, so I can just 'ack' my way through the source from identifier to identifier.
It would be super awesome if omniref in that 'view source' block would find identifiers, and try to guess what they refer to, and make them clickable so we could really just browse through the source. The user interface is perfect too for fuzzy search, as it shows the item its most confident in in the main window, but has the rest of the results in the bar on the left side, can't go wrong with that!
Great example. A code browser is on our radar, but it would be a big enough undertaking to do "right" that it hasn't made the cut for low hanging fruit. Our next step may be to just hyperlink all methods/classes/constants in the source to their docs, and from there, the real work left will be front end js.
P.S. Omniref documents "private" methods, even rdoc's :nodoc: methods, with their source. Mainly because of this problem, Ruby documentation isn't complete unless you can view the entire implementation.
Most Ruby implementations have some kind of inline cache - they remember at each call site what object you normally see there, and what method you're normally calling. Could you get that data out and use it to report the correct method at each call site?
The dynamism of ruby does make things difficult, if not impossible, to fully realize until runtime. Incidentally, tests are popular in ruby, and give us runtime examples to work with for stronger analysis.
If we're just spitballing, as big as TDD is in rubyland, I'd love to see tests themselves become first class documentation, built with the rest of the class docs as yet another form of annotation.
Coming from Java the biggest surprise to me was a lack of good API documentation for Rails and Ruby gems.
Javadoc used to drive my productivity. It is quite frustrating sometimes with Rails that more often than not I can't find good api docs.
Rails and various Ruby gems have very good tutorials, but sometimes no api docs at all.. Tutorials are great for getting started, but you're in trouble when when you want to do something slightly unusual.
Slowly I'm realising that to be really good with Rails you need to look into the source code of libs you're using to get a better grasp.
As an example, I wanted to find out if it was possible to do something with ActiveRecord.to_json that I haven't seen in any tutorials. Spent 10 minutes searching for docs and then looking at the code.. which in Java would have been done in 20s.
Having said that, I really like Rails and enjoy a lot of productivity gains. I just wish it had better api docs.
The relative terseness and readability of Ruby code makes it so that turning to reading the source code is often favored over a lot of documentation.
It would be a bit more difficult to operate in the same way in a Java environment.
That said, the fact that it's kind of viable in Ruby doesn't mean that it's the best thing. Ultimately, I agree with you: better documentation would be very welcome.
Yes and source code only tells you how it does work not what it should do. I find it tricky to follow a call path through polymorphic and mixin based code.
I really love javadoc (pretty sure thats what generated the AS3 docs from back in the flash days). I feel the same as you, AS3 I could code from the docs, Rails I find myself searching online
Tim. You're a pessimistic bastard but I love you. And I love Omniref. (When I remember to use it.) Maybe consider a sublime text plugin and complete sublime's inevitable march toward IDE-dom?
Often times to understand how a piece of Ruby code works it's not enough to just look at the source of that specific method. For example if I type in 'ActiveRecord.find', the second result is the one I want, ActiveRecord::FinderMethods.find, and I click it. The documentation is a bit long, so I click 'view source'. The code is short and sweet, but not very enlightening, it's just a wrapper around 'find_by_ids'.
Now luckily 'find_by_ids' is a public method so that's documented and I can search for it. But almost guaranteed at some point the code is going into private api's and I can't use the documentation anymore to understand it.
This is why I always have a local checkout of the Rails code and any other big gems, so I can just 'ack' my way through the source from identifier to identifier.
It would be super awesome if omniref in that 'view source' block would find identifiers, and try to guess what they refer to, and make them clickable so we could really just browse through the source. The user interface is perfect too for fuzzy search, as it shows the item its most confident in in the main window, but has the rest of the results in the bar on the left side, can't go wrong with that!