From: Hugh Sasse <hgs@...>
Date: 2010-01-26T17:51:33+09:00
Subject: [ruby-core:27846] Re: [Bug #2656] Inconsistent docs for Zlib.



On Tue, 26 Jan 2010, Yui NARUSE wrote:

> Issue #2656 has been updated by Yui NARUSE.
> 
> Category set to lib
> 
> >   Zlib::GzipWriter.open(filename, level=nil, strategy=nil) { |gz| ... }
> > (snip)
> > and Zlib::GzipWriter#wrap.
> > However, there is no wrap method documented on that page.
> 
> This typo of Zlib::GzipWriter.wrap.
> 
> >   Zlib::GzipReader.open(filename) {|gz| ... }
> > (snip)
> >   ZLib::GzipReader.wrap.
> > Again, there is no wrap method documented on that page.
> 
> This is correct.
> 
> >  GzipFile.wrap(...)
> >  See Zlib::GzipReader#wrap and Zlib::GzipWriter#wrap. 
> 
> This is typo of Zlib::GzipReader.wrap and Zlib::GzipWriter.wrap. 
> Zlib::GzipReader#wrap and Zlib::GzipWriter#wrap are't exist. 
> 
> > Both GzipReader and GzipWriter inherit from GzipFile which:
> 
> Yes, so Zlib::GzipWriter.wrap and Zlib::GzipReader are inherited methods
> of Zlib::GzipFile.wrap.
> 
> > This looks to me as if the structure have changed, and maybe GzipFile#wrap
> > just raised an exception in the past, to create an abstract method. I've
> > not checked earlier versions to see.  However, for the superclass to 
> > refer to the subclasses for documentation seems odd.
> 
> Those documents are confusing but they are only typo.
> Things didn't change.

OK, I thought that was possible, too. 
> 
> If you create a patch for Ruby's trunk, I'll merge it.
> Now this ticket move to Ruby 1.9.

OK, I'll see what I can do.  Do you just want me to (effectively)
s/Gzip(Read|Writ)er#wrap/GzipFile#wrap/
for these cases?  Is that the desired fix?
> 
> P.S.
> We recommend:
> * a problem is in trunk (unstable trunk/branch), the patch should be for trunk
> * a problem isn't in trunk but in ruby_1_8 (stable branch), the patch should be for ruby_1_8
> * a problem is only in release branch, the patch should be for the branch
> If you test some releases please write them, and we can remember to backport to the release branch.

OK, I'll explore the structure in a little more detail, then, so I'm
working on the correct part.  Thank you.

        Hugh