From: Hugh Sasse <redmine@...>
Date: 2010-01-26T04:38:15+09:00
Subject: [ruby-core:27828] [Bug #2656] Inconsistent docs for Zlib.

Bug #2656: Inconsistent docs for Zlib.  [ruby-core:27692]
http://redmine.ruby-lang.org/issues/show/2656

Author: Hugh Sasse
Status: Open, Priority: Normal
ruby -v: ruby 1.8.7 (2008-08-11 patchlevel 72) [i386-cygwin]

(Putting this in redmine so it will be found)

http://ruby-doc.org/stdlib/libdoc/zlib/rdoc/classes/Zlib/GzipWriter.html

has
   Zlib::GzipWriter.open(filename, level=nil, strategy=nil) { |gz| ... }

   Opens a file specified by filename for writing gzip compressed
   data, and returns a GzipWriter object associated with that file.
   Further details of this method are found in Zlib::GzipWriter.new
   and Zlib::GzipWriter#wrap. 

However, there is no wrap method documented on that page.
Similarly,

http://ruby-doc.org/stdlib/libdoc/zlib/rdoc/classes/Zlib/GzipReader.html

has:
   Zlib::GzipReader.open(filename) {|gz| ... }

   Opens a file specified by filename as a gzipped file, and returns
   a GzipReader object associated with that file. Further details of
   this method are in Zlib::GzipReader.new and
   ZLib::GzipReader.wrap. 

Again, there is no wrap method documented on that page.

Both GzipReader and GzipWriter inherit from GzipFile which:

http://ruby-doc.org/stdlib/libdoc/zlib/rdoc/classes/Zlib/GzipFile.html

does have a wrap method documented, but it says:
  wrap(...)

  See Zlib::GzipReader#wrap and Zlib::GzipWriter#wrap. 

which, as we have shown, do not have this documented or even override it.

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.

I have found this:

ruby-1.8.7-p173/ext/zlib/doc/zlib.rd

which has:


--- Zlib::GzipFile.wrap(args...) {|gz| ... }

    See ((<Zlib::GzipReader.wrap>)) and ((<Zlib::GzipWriter.wrap>)).

and

--- Zlib::GzipReader.wrap(io) {|gz| ... }

    Creates a GzipReader object associated with ((|io|)), and
    executes the block with the newly created GzipReader object,
    just like File::open. The GzipReader object will be closed
    automatically after executing the block. If you want to keep
    the associated IO object opening, you may call
    ((<Zlib::GzipFile#finish>)) method in the block.

and


--- Zlib::GzipWriter.wrap(io[, level[, strategy]]) {|gz| ... }

    Creates a GzipWriter object associated with ((|io|)), and
    executes the block with the newly created GzipWriter object,
    just like File::open. The GzipWriter object will be closed
    automatically after executing the block. If you want to keep
    the associated IO object opening, you may call
    ((<Zlib::GzipFile#finish>)) method in the block.


which looks rather like duplication, and might be better if the 
description were moved up into GzipFile

I don't mind creating a patch to fix this, but maybe there are good
reasons why this came about, and a better way to fix it, so that the
docs really do end up in the subclasses.  But since the C source
doesn't have the rb_define_method calls to create the wrap methods
in the subclasses, I can't see this being picked up correctly by
Rdoc from the subclasses.

Does anyone have any wisdom to share about this before I create a 
patch to move the descriptions up GzipFile, and thereby combine them? 

        Hugh


----------------------------------------
http://redmine.ruby-lang.org