comments from an experienced programmer on ruby docs

Hey there, I am learning ruby for my hard drive backup project:

http://www.subspacefield.org/security/hdb/

Ruby is a cool language, but the documentation is a little hard to
read.  Many people use the term "Foo#whatever" with the assumption
that one knows what it means - I originally assumed it was an instance
method, but now believe it is a class method.  Since it's a special
character, you can't really search google for it easily.

Regarding http://rubylearning.com/: the formatting of the text boxes
is awful, since at least on my computer, it requires manually scrolling
every one, effectively peering at the program through a tiny viewport.
The content, however, is very good.

One thing that needs discussion is how everything except ints and
floats (and perhaps some other types) are passed by reference.  I got
really bit by passing strings into constructors, and the constructor
later modified the string, and that changed the value of the thing I
passed in.  This is true for arrays as well, and any user-defined
objects.  Since this is a change from how many other scripting
languages work, you should point it out a little better (it is hinted
at).  In essence, you'll want to dup any parameter before modifying it
(unless again it is an integer or float).  I assume these are the
objects that correspond to "what fits in a register" in C.  I make it
a practice to dup everything that gets passed into a constructor.  In
any case, this is a lot closer to C than I expected.

Regarding:

http://www.ruby-lang.org/en/documentation/ruby-from-other-languages/to-ruby-from-python/

* The notions of equality (== vs eql?) differ from that of python.
* The keyword parameter stuff can be moved from the higher level page to this one,
  since it's targeted at python programmers.

Generally:

You should show how to delegate a method generically.  In other words,
"I don't know how the delegatee will implement this, how the caller
will invoke it, or whatever - I just want to pass calls to method blah
through"
--

-- 
A Weapon of Mass Construction
My emails do not have attachments; it's a digital signature that your mail
program doesn't understand. | http://www.subspacefield.org/~travis/ 
If you are a spammer, please email john <at> subspacefield.org to get blacklisted.