From: Markus Fischer <markus@...>
Date: 2011-06-16T01:23:43+09:00
Subject: Re: Ruby 1.9.3 documentation challenge

Hi,

based in your coverage @
http://segment7.net/projects/ruby/documentation_coverage.txt I took a
few looks, e.g. it says:

# in files:
#   ext/socket/raddrinfo.c
#   ext/socket/lib/socket.rb

class Addrinfo
end

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 .

Next sample was

class CSV # is documented

  # in file lib/csv.rb
  def raw_encoding(default = Encoding::ASCII_8BIT); end

end

taking a closer look, it's method marked private.

I've a few questions now:

- 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?

- 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.

- 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?

thanks for clearing things up,
- Markus