From: Eric Hodel <drbrain@...7.net>
Date: 2011-06-18T07:51:36+09:00
Subject: Re: Ruby 1.9.3 documentation challenge

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

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.