Re: How to fix docs for Zlib::GzipReader#wrap ?

  This message is in MIME format.  The first part should be readable text,
  while the remaining parts are likely unreadable without MIME-aware tools.

---476953799-636249321-1264015035=:2290
Content-Type: TEXT/PLAIN; CHARSET=ISO-8859-15
Content-ID: <[email protected]>
Content-Transfer-Encoding: quoted-printable

On Wed, 20 Jan 2010, Roger Pack wrote:

> > I've submitted doc patches before, so that part of the process, inclu=
ding
> > discussing it as per this URL, is OK. =A0My difficulty is that I'm fa=
iling
> > to see how to get Rdoc to pick up the docs associated with rb_gzfile_=
s_wrap
> > and associate them correctly with GzipReader and GzipWriter. =A0Maybe=
 I
> > don't need to do much that's special for that to work, and just make =
sure
> > I don't refer to a specific class in the docs there?
>=20
> if there's a .document file you'll have to specify the .rdoc file
> there [and all others]

I don't think that's it: I've patched a whole bunch of those for when
1.8.6 came out: they just tell rdoc which files to read to get the docs.
They don't associate methods with more than one class which is what
seems to be needed here.

> if there's not, you'll either have to create one or move the docs to be=
 inline.

I know they need to be inline in the C code. The question is how to get
the method wrap associated correctly with GzipReader and GzipWriter
when the C source says it is defined against cGzipFile. =20
cGzipFile looks like it is the GzipFile class, and the wrap method of
that says:

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

  wrap(...)

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

But they are not defined in the respective documentation for those
classes, at least in the source.  Further examination shows they=20
GzipWriter and GzipReader are subclasses of GzipFile, so they would
inherit from there, so why is the superclass documentation pointing
to the docs of the subclasses that don't override this method, and=20
why does the rd document I pointed to earlier (zlib/doc/zlib.rd)
have the docs for the subclasses, rather than the superclass which=20
refers downwards?

> -r
>=20
> > It would be moving the comments inline, but it's doing it in
> > such a way that it gets picked up correctly. =A0For Ruby source
> > this is much more straightforward, than for C source.
>=20
> looks like there's some examples here:
> http://rdoc.rubyforge.org/RDoc/Parser/C.html

Thanks, but that doesn't answer the question about correct association
when it is different from what the c code says (for some reason as yet
unknown to me).
>=20
> -r
>=20
>=20
        Thank you
        Hugh
---476953799-636249321-1264015035=:2290--