On Jun 15, 2011, at 9:23 AM, Markus Fischer wrote:
> based in your coverage @
> http://segment7.net/projects/ruby/documentation_coverage.txt I took a
> few looks, e.g. it says:
>=20
> # in files:
> #   ext/socket/raddrinfo.c
> #   ext/socket/lib/socket.rb
>=20
> class Addrinfo
> end
>=20
> I took a look at ext/socket/raddrinfo.c and found =
addrinfo_initialize()
> with lots of documentation above it which I also see reflected at
> http://www.ruby-doc.org/core-1.9/classes/Addrinfo.html#M001733 .
>=20
> Next sample was
>=20
> class CSV # is documented
>=20
>  # in file lib/csv.rb
>  def raw_encoding(default =3D Encoding::ASCII_8BIT); end
>=20
> end
>=20
> taking a closer look, it's method marked private.
>=20
> I've a few questions now:
>=20
> - for Addrinfo, is there really still something missing or does this
> come from the additional ruby code in ext/socket/lib/socket.rb and the
> coverage report just can't connect both of these together?

There is no class documentation for Addrinfo.  Either a Document-class: =
Addrinfo needs to be added to the C file or a class comment needs to be =
added to the ruby file.

> - Is there an encouragement to document private methods? If not it =
would
> be nice if they could be omitted from the coverage. Otherwise just so =
we
> know what the goal is.

Yes, but if the maintainer of the library decides that a private method =
is also an implementation detail it may be hidden by :nodoc:

Private methods can be API.  For example, when you subclass you may need =
to call a private method for proper operation.

> - While I was looking at addrinfo_initialize() in =
ext/socket/raddrinfo.c
> and then looked at
> http://www.ruby-doc.org/core-1.9/classes/Addrinfo.html#M001733 , I
> noticed that at the HTML page there is a typo, it says "The instnace
> contains..." but the docs in the code are right. Looking with git =
blame
> at the code docs it said last change was in 2009-11-04 12:02:37 . =
That's
> now more than two years and I'm wondering if looking at
> http://www.ruby-doc.org/core-1.9/ will give generally a wrong =
impression
> because the docs aren't up to date? Is there some automatic =
generation?

I'm not sure how ofter ruby-doc.org updates, I don't maintain it.=