Misc #15224

Updated by nobu (Nobuyoshi Nakada) over 2 years ago

Today I looked at: 

 The example to this method is this: 
 a = [ "a", "b", "c", "d", "e" ] 
 a.replace([ "x", "y", "z" ])     #=> ["x", "y", "z"] 
 a                                #=> ["x", "y", "z"] 
 What confused me was that I was looking at the method called `initialize_copy` 
 but the example showed `.replace()`. 

 I then looked at `#replace` there: 

 And it was virtually identical to `initialize_copy`. 

 I assume the examples for `.replace()` are correct; and perhaps `initialize_copy` 
 is just an alias? I am not sure, but I would like to suggest to make the documentation, 
 in particular the example, a bit more consistent. 

 When you click on "view source" to look at the C code, they show the very same 
 content, so I believe that initialize_copy is merely an alias to replace; but I tried 
 this and they are not fully equivalent:  
 x = [1,2,3] # => [1, 2, 3] 
 x.initialize_copy [4,5,6] 
 Traceback (most recent call last): 
         2: from /System/Index/bin/irb:11:in `<main>' 
         1: from (irb):2 

 NoMethodError (private method `initialize_copy' called for [1, 2, 3]:Array) 
 x.replace [4,5,6] # => [4, 5, 6] 
 works. So I assume that `initialize_copy` is like `.replace()` but is a private 
 method instead. 

 Perhaps it may help to add a sentence below the documentation of 
 `replace()`, to explain what the use case for `initialize_copy` is. Or to perhaps 
 mention that it is an alias. 

 At the least how it is right now is that people may read `initialize_copy`, initialize_copy, 
 but then see an example of `#replace`. #replace. (Perhaps an example for  
 `initialize_copy` initialize_copy may help, but either way, I think the current docu-example  
 is not ideal).