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
Information and Educational Technology
Kwantlen University College - 604-599-2120
“So powerful is the light of unity that it can illuminate the whole
earth.” --Bahá'u’lláh
javier ramirez [email protected]
Sent by: [email protected]
27/02/2007 09:28 AM
Please respond to
[email protected]
To
[email protected]
cc
Subject
[Rails] Re: Decent documentation?
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 
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
Estamos de estreno… si necesitas llevar el control de tus gastos
visita
http://www.gastosgem.com !!Es gratis!!
