
What's relevant in the Ruby Universe? - timr
http://www.omniref.com/blog/blog/2014/02/18/whats-relevant-in-the-ruby-universe/
======
tinco
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!

~~~
montanalow
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.

~~~
chrisseaton
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?

~~~
montanalow
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.

------
vrepsys
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.

~~~
Legion
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.

~~~
josephlord
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.

------
randall
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?

