On Apr 8, 2008, at 12:05 PM, Jeremy McAnally wrote:
Someone has suggested that but I haven’t looked at it. I haven’t
gotten far with the whole ruby_parser port (it’s in place but didn’t
take long to write), so switching to something would be fine. I’ll
look into that tonight then, since I didn’t know 1.9 had it built in.
I spoke to Eric via mailing list who said he wanted to use ruby_parser
for a new RDoc, but ripper seems like a more logical choice to me.
It’s easy to beat up the documentation. It’s a time-honored tradition.
Still, the fellow’s post zeroed in on digest, and the fact that it’s
not documented at all. If you go to php.net (ick) and type ‘sha1’ in
the search box, you get this:
PHP: sha1 - Manual
(or maybe something else if you aren’t in the US). The point is, the
answer is relevant and if you knew why you needed SHA1, you would
probably have your answer including an example.
For whatever reason, PHP has quite usable documentation. Now, for a
different experience, go to http://msdn.microsoft.com and type
‘sha1’ (assuming you have no objection to installing Silverlite). You
will get tons of information, but you have to do a lot of wading to
find what you’re looking for. Ruby can do better.
My opinion (FWIW). Good documentation should be:
Fast to load
Cross browser
Cross platform
Downloadable as an alternative
Extremely searchable (consider typing “encryption” in PHP’s search box)
Commentable by the community
It should:
Contain specific information about a module’s “purpose”, a class’s
“overall description”, and specifics on argument types, defaults, and
return types, as well as exceptions raised. Examples are extremely
useful.
Having pontificated for some time, I recognize that this is a tall
order and that the main problem is not that the Ruby documentation is
“not there”, but rather that the coverage is not uniform –
particularly in the standard library. As an example, pretend you don’t
know much about YAML and want to figure out how to load a YAML
document from a file. What is your search strategy and how many clicks
does it take you to arrive at sufficient information using the current
API docs.
Just my $.02
