Decent documentation?

I know that the rails framework has "good" documentation, but I've found it to be very shallow. I don't know how many times I've tried to look up a method (like the content_tag helper, for example) only to find that it takes ":options" but has no documentation as to what those options are. At least, not that I can see.

Don’t know where you where looking for it, but on api.rubyonrails.org
this is the explanation for “content_tag” helper.

Hi,



this one, file_field_tag (and most of the other methods on that page as well)...
It says it takes options, but it doesn't say what they are. At the top of the page it does say this: "NOTE: The html options disabled, readonly, and multiple can all be treated as booleans. So specifying :disabled => true will give disabled="disabled"."

well, a bit before that line it says "
Provides a number of methods for creating form tags that doesn‘t rely
on conventions with an object assigned to the template like FormHelper
does." And in FormHelper you have the tags where it says any other
options for the input tag can be passed in the options hash, so it’s
just a link away :wink:

but even if this assumption is accurate the docs don't specify if those html attributes account for the full range of options or if they are a subset of the options that are valid.

In my experience, when the range of options is limited it usually says
so, stating which are the valid options. When there are no descriptions
of the options it usually means the method is “agnostic” about the
options and will just delegate by letting all the options get through.
As i said, that’s the general pattern I see, but for sure you could
find some exceptions and examples of underdocumented methods.

Am I missing something else?

Well… maybe not missing something… but maybe not using the powerful
resource of “view source” in all the API methods. If you see the source
of whatever of the methods of that page, you’ll see they just call to
“tag” and pass the whole hash of options. And then if you look the doc
for “tag” you’ll see it says it admits whatever you want to pass.

And I didn't mean to imply that I thought the docs were bad... The ruby and rails docs are second only to the JDK docs in quality (in my mind) and it is only second because Java's strong typing makes it easier to document things clearly.

Static typing can be a good thing sometimes, I agree. Ruby’s
flexibility is not free. Anyway I’d say the doc is not second to the
JDK in quality… after all you have the links to the source code in
every rails method, and being generally short methods I’d say the
source code it’s almost the best documentation you could ask for.

Anyway, I’m not trying to say ruby/rails is better/worse than java or
whatever… to each its credit and I’d say both are pretty well
documented.

But, as I said in my first e-mail… The API doc (in any programming
language) is just a reference. You cannot try to learn only by looking
at it. I insist on my advise about getting some good
books/tutorials/documents to look for help when API is not enough.

Regards,

javier ramirez

To my mind, the PHP Manual has set the
bar for documentation long ago. Far more valuable than including source
snippets are the complete workable examples for every type, function, control-structure,
expression, class and object. But it doesn’t stop there, documentation
and examples are given for installation on the big three platforms, along
with in-depth discussion on security and features.

It’s just so darn well organized, and
it’s all in one place. (I don’t even work in PHP and I’m ranting about
it. Fact is I’m jealous).

:^)

Regards,

Dave