[Vit-discuss] Ruby-Lang Redesign Feedback Requested

[Mauricio Fernandez]

Hi,

On Thu, Aug 24, 2006 at 03:56:11PM -0400, John W. Long wrote:
> We are getting really close to launching the new Ruby-Lang Web site and 
> could use your help! Almost all of the technical details are finished 
> and we are polishing the last little bit of content.
> 
> If you have a minute, zip on over to the new Web site and click around:
> 
> http://new.ruby-lang.org
> 
> See something amiss or askew? Let us know. This isn't a time for 
> nit-picking, but if you see something misspelled or believe something to 
> be unclear, speak up! Please keep comments short, positive, and to the 
> point. We've put a lot of work into this and would like to put it live 
> as soon as possible.

I found a couple inaccurate explanations on
http://new.ruby-lang.org/en/documentation/ruby-from-other-languages/

    Methods

[...]

    Ruby differs slightly. public is, naturally, public. private means the
    method(s) are accessible to a class's and its ancestors' instances.  
              =========================================================
This seems unclear or confusing at worst.         ^^^^^^^^^  ^^^^^^^^^
                                                  especially this
    
    Only self is allowed to be the receiver of a private method
    call.

Based on this, somebody could expect
  
   self.some_private_method

to work, so the explanation should probably be reworded to mention the "no
explicit received allowed" rule [1]. Also, the example given below is
ambiguous. One can easily believe that other.func is failing, when actually
self.func won't work once #func is made private:

  def ==(other)
    self.func == other.func
  end



Also saw a small braino:
    
    Operators are syntactic sugar
  [...]

  The methods below are not syntactic sugar, though. They are not methods,
      =======
      operators
  and cannot be redefined:
  [...]




This made me chuckle

 http://new.ruby-lang.org/en/documentation/ruby-from-other-languages/to-ruby-from-c-and-c-/

 [...]
 Similarities with C
 As with C, in Ruby,...

     * the language is strongly typed.

(C isn't).


Feel free to ignore these observations if you don't see much value in them.  

I guess there are still a few typos/brainos to be found, but reporting them
via this ML to have them fixed by somebody else looks like way too much work
for all parties involved.  Are you planning to provide some more convenient way
to give feedback (such as third-party modifications that can be approved by
the admins, or a similar mechanism)? If not, what must one do to get the
"typo corrector" access bit? [On a related issue, where will the contents
come from, esp. news and such? Any plans yet?]


[1] This can probably be skipped, but if the exception regarding foo=
methods is mentioned, an example like this might help:

class X
  def a=(x); x end
  private :a=
  def foo; self.a = 2 end
end

X.new.foo                                          # => 2
X.new.a =  1
# ~> -:8: private method `a=' called for #<X:0xa7d34850> (NoMethodError)

-- 
Mauricio Fernandez  -   http://eigenclass.org   -  singular Ruby