How to fix docs for Zlib::GzipReader#wrap ?
Hugh Sasse <[email protected]> Wed, 20 Jan 2010 14:16:00 +0000 (GMT)
| Newsgroups | gmane.comp.lang.ruby.documentation |
|---|---|
| Message-ID | <[email protected]> |
The docs for Zlib on line, for example
http://ruby-doc.org/stdlib/libdoc/zlib/rdoc/classes/Zlib/GzipReader.html
have phrases such as:
Further details of this method are in Zlib::GzipReader.new and
ZLib::GzipReader.wrap.
but wrap is not actually listed in that document. I have found docs
for it in
ruby-1.9.1-p376/ext/zlib/doc/zlib.rd
and in
ruby-1.8.7-p173/ext/zlib/doc/zlib.rd
[1], and I consider it fair enough that rdoc didn't pick this up
(different directory, different format, different extension).
Because I don't do enough with C extensions, I don't know how to fix
the source to get this picked up correctly by rdoc.
ruby-1.8.7-p173/ext/zlib/zlib.c has
rb_define_singleton_method(cGzipFile, "wrap", rb_gzfile_s_wrap, -1);
but
cGzipFile = rb_define_class_under(mZlib, "GzipFile", rb_cObje ct);
and there doesn't seem to be much to say that wrap should appear as a
method of GzipReader or GzipWriter, according to my quick searches.
Is it actually possible to document this in the source so Rdoc will
pick this up correctly? Is there anything concise someone can point
me at that will enable me to write the comments in the right place
and style for something more useful to show up, even if perfection
is not attained? I don't mind trying to make something acceptable, but
I'm trying to fix some code using wrap, so don't want to spend too
long on the details of creating the docs, if that can be avoided.
Thank you,
Hugh
[1]
It says:
--- 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.