[LRUG] Ruby world and documentation

[Peter Vrabel]

Hi guys,

a bit of introduction at the beginning. I've got C++, Unix background,  
doing system level programming, but I'd been using Ruby to create various  
internal tools, but I never got deeper into it, until recently. I'm just  
finishing the first milestone doing remote API for a web community portal.  
I use Zeromq and Google Protocol Buffers to scale it well (with bunch of  
other gems, like Sinatra, rest-client, ...). I've learnt a lot about Ruby  
during this, getting into using it idiomatically and I really like it.

My observation and question is about libraries/gems documentation. I'm   
finding myself quite often reading gems code just to understand, how can I  
use it. Mostly, they've got s simple introduction in README and then  
you're on your own. But I am used to having a comprehensive reference  
documentation/manual, as that's what you've got in C++, Unix world. You  
can read about 'corner cases' which would otherwise slip by your  
attention. For example that you can get value 60, sometime 61 for seconds  
when getting current timestamp. So called 'leap seconds'. In Ruby,  
documentation seems to me 'more shallow'. Please, don't get me wrong, I'm  
not saying it's bad. It probably comes with the fact, that Ruby is easy to  
pick up and just to do your work. I definitely learn when reading others  
code (obviously ;). I would just like to hear what other folks think about  
it and go about it. And is there any handy application that show, search  
installed gems documentation apart from a command line 'ri'?

Thanks a lot.

Cheers,
   kybu