From: "Michael W. Ryder" <_mwryder@...>
Date: 2009-10-07T13:15:07+09:00
Subject: Re: Ruby for the wrong reason

Walton Hoops wrote:
>> From: Michael W. Ryder [mailto:_mwryder@worldnet.att.net]
>> How much of the Ruby standard library is a port of the C standard
>> library?  This has been documented since at least 1992 and is readily
>> available.
> 
> 
> This is at least the second person to say this, and I find it a little
> scary. Just because C has these functions documented does NOT mean that
> it is OK for Ruby not to.  

I think it is more a matter of priorities.  While you may find that the 
lack of documentation of a function that is copied from C upsetting, I 
would rather the developers use their limited time for more important, 
to me at least, things.  I prefer hard copy documentation and having a 
copy of the C Standard Library on my desktop gives me this ability.  I 
have never been able to get the Ruby documentation to work, probably 
because it was faster to grab the book.

Just because C has a function named sprintf
> does NOT mean that a Ruby/Python/PHP/any other langauges' sprintf will
> work the same way.
>
I would expect anyone making a new version of sprintf to rename the 
function to forestall the inevitable tarring and feathering.  It would 
be like changing the meaning of black to mean light purple.  People 
expect words, and function names are words, to not change.

> Imagine this for a minute: there is a new browser in town. Everyone
> loves it. So you decide to give it a shot.  You find a really cool page
> and you want to bookmark it. You look around, find the bookmark menu
> and click add.  It provides two empty textboxes with no labels. So you
> look up adding a bookmark in the docs, and there is nothing there.  So
> you head for the mailing list and ask for help.  Everyone says "No need
> to document it, it's thoroughly documented in Firefox's documentation"
> Is that good documentation pratice?
>
I am not saying that it is good practice but there is some logic in 
this.  If your new browser used Firefox as a base if a change was made 
to Firefox the change may percolate up into the new browser.  So there 
will be changes made to the documentation.  Which do you think will 
happen first, the well supported Firefox browser, or the small team 
using the Firefox code?


> Bottom line: When I go to look up a function and I find no notation
> whatsoever (not even "see 'x' function in c") it is not good
> documentation, and it does not make for a good user expierience.
> 
The documentation for the language does not bother me anywhere near as 
much as the changes breaking old code and no way to find out what is 
broken without experience.  Different documentation faults.

> (This from a newbie who is loving the language, yet constantly,
> hating the lack of documentation)
> 
>