Rails API documentation is far from perfect, but a surprising amount of the important stuff is covered in a few consolidated locations. The documentation for some modules is often consolidated in a more central location so you can get a better overview of the whole API. See ActionController::Base, ActiveRecord::Base, ActiveRecord::Associations::ClassMethods for example. As for I18n, well, I18n is an external gem, it is not core to Rails which is why it is not documented there.
No one is arguing that Rails API documentation is newbie friendly, but I would argue that the purpose of API documentation is not to introduce people to the framework; it's reference material. The Rails Guides are pretty good (if not lagging a bit for some aspects of Rails 3) and I would put them up against any other framework documentation I've used.
Being able to look at a function, have clear documentation WITH EXAMPLES was brilliant -- being able to see some of the common questions and resolutions from users was exemplary.
I know that the python docs are largely considered aces, but I have yet to see a language reference as good as the PHP documents. I hate the language, but it was the first language I could actually learn from its own documentation.
I've seen this (similarly highly-voted) comment made elsewhere. I just don't get it.
The PHP docs are often woefully incomplete in their explanation of functions. The user-submitted comments are the blind leading the lame, often containing competing solutions to the same problems, all of which are incomplete and poorly documented.
Aside from several highly-voted comments in discussions, though, the PHP documentation doesn't seem to be a frequently cited example of quality. I find that strange.
Programming tool that have the best documentation, to me, is jQuery. I think it's even better than php.net
Here you go:
http://www.lispworks.com/documentation/HyperSpec/Front/index...
I started with railsapi.com - selected something at random: first ActionView::Layouts (seems like a crucial class):
Right... where does the "lookup context" object go? What is "layout" What's returned? Where does it "find the layout"? Why does this method exist? What error is raised? Ok - maybe I just chose something that's not popular - another try is ActionView::PathResolver: You're kidding me, right? Ok - something easy this time - "Float" -> "round(precision = nil) - Rounds the float with the specified precision." Rounds which way? What type of rounding is used? How does it behave for infinities and -epsilon? Something important "I18n" - there is NO documentation at all.I checked APIdock, thinking it might be better - it took a lot of clicking to get to a class which had any documentation at all (ActiveRecord in this case). If you check "browse", you'll see yourself how many classes lack any kind of description...
Summing up - I'm not sure about the screencasts, guides, etc., but API docs are almost non-existent.