Andrew G.berg wrote:
Can you give examples of the vagueness.
Yes, I can?
What does the block that you can pass to
ActionView::Helpers::FormTagHelper#form_tag() do, and why does it exist?
What are the possible valid options to
ActionView::Helpers::ScriptaculousHelper#sortable_element(), should the
keys be strings or symbols, and how do you represent booleans?
If you merge() two HashWithIndifferentAccesses, one with a string key
and the other with a symbol key that HWIA treats as the same, which
value gets kept?
Where is routing documented?
When you assert_routing, what format should the expected options hash
take, and how should you express ‘*foo’ route elements? What does the
extras hash do?
I’m not asking these questions because I want to know the answers, I’m
just pointing out some of the holes in the docs at api.rubyonrails.com
I’ve run into that have had me digging into the source. I’m not
pointing them out to denigrate the Rails-core team in any way, but if I
didn’t have access to the source, I certainly couldn’t answer these
questions (and others like them) without jumping through a lot of hoops.
I have found the api docs to
be the best source of information (and a good source at that), of how
Rails actually works.
It’s good, but it’s not great. If I was much of a documentation writer,
I’d feel a little more confident about knocking up some doc-patches, but
I’ve got no idea if a) I’d have time to do it well, or b) I could do
them well enough for them to be accepted.