To my mind, the PHP Manual has set the bar for documentation long ago.
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
work in PHP and I’m ranting about it. Fact is I’m jealous).
Information and Educational Technology
Kwantlen University College - 604-599-2120
“So powerful is the light of unity that it can illuminate the whole
javier ramirez firstname.lastname@example.org
Sent by: email@example.com
27/02/2007 09:28 AM
Please respond to
[Rails] Re: Decent documentation?
this one, file_field_tag (and most of the other methods on that page as
It says it takes options, but it doesn’t say what they are. At the top
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
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
stating which are the valid options. When there are no descriptions of
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
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
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)
it is only second because Java’s strong typing makes it easier to
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
after all you have the links to the source code in every rails method,
being generally short methods I’d say the source code it’s almost the
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
it. I insist on my advise about getting some good
books/tutorials/documents to look for help when API is not enough.
Estamos de estreno… si necesitas llevar el control de tus gastos
http://www.gastosgem.com !!Es gratis!!