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
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
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.