Ruby core documentation quality [closed]

Question

I'm relatively new to Ruby and have limited time therefore I try out simple things. Recently I needed to create a file and because I'm lazy as hell, I run to Google. The result:

File.open(local_filename, 'w') {|f| f.write(doc) }

Shame on me, it is very straightforward, should have done it myself. Then I wanted to check what ruby magic the File class' methods offer or if there's any 'simplification' when invoking those methods, so I headed for the documentation here, and checked for the File class.

• 1.8.6 documentation presents me with "ftools.rb: Extra tools for the File class" under 'File' class, which is not what I'm looking for.
• 1.8.7 documentation seems OK for 'File' class, there are a plethora of methods. Except 'open'.
• 1.9 documentation finally shows me the 'open' method.

And I had an almost same tour with Net::HTTP.

Do I exaggerate when I think good old Turbo Pascal's 7.0 documentation was better organized than Ruby documentation is right now? Is there any other source for the uninitiated to collect knowledge? Or is it possible that I just tumbled into a documentation hole and the rest are super-brilliant-five-star organized?

Thanks

Answer 1

You have to remember that Ruby is an object-oriented language, and a lot of objects in the Standard Library, are built on-top of other objects. In addition, many are extended by modules, which add in new functionality.

So, in the documentation you need to see what things an Object is built-upon. In File's case, it's built on top of IO, which will have a lot of the functionality you'd expect to find in a standard "file" class.

I agree that some of Ruby's documentation is disjointed. I think it's important to get a good book; I recommend the one we refer to as "The Pickaxe Book", AKA "Programming Ruby". There are many other good books, along with some good documentation on line, but this is a great go-to book. The [first edition] is available for free online; It is a bit outdated but still useful.

I'd recommend browsing through some of the other questions similar to this on SO for more suggestions.

I also keep links open to Ruby 1.9's Core and Keyword docs. And, finally, the top of the Ruby-Docs site points to lots of good info though you do have to pay attention to which version the docs are for.

Finally, don't ignore the built-in help: ri at the command-line is a fast source of info on your own machine that should contain documentation for the core and standard library, plus all the gems you have installed. ri open would have told you all the places "open" was defined. ri File.open would have given you a lot of information about that command.

---

When I started with Ruby, the biggest impediment to learning the language was the documentation. I still find it a lot easier to get info about Perl and Python, and feel like Ruby should use those as examples. That doesn't change my enjoyment of using Ruby though. It's a great language and once getting over the initial hump I like it more and more.

@phoffer recommends RubyDoc.info in the comment above. I hadn't seen that site but it looks good. I like that it shows what a class inherits from clearly.