Can we make it to 60% coverage? That's only another 1626 items to document!
I've written a blog post with further information including a link to an hourly-updatidng coverage report and a tutorial by Steve Klabnik on how to write documentation and get it committed, the short link is here:
If you've never contributed to Ruby before, I wrote up this blog post,
explaining just how easy it is for you to add the documentation that Eric's
asking for.
# 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! I never really contributed to Ruby, but if it's that easy I'll
probably do so.
···
On 5/11/11 5:15 AM, Steve Klabnik wrote:
If you've never contributed to Ruby before, I wrote up this blog post,
explaining just how easy it is for you to add the documentation that Eric's
asking for.
On Wed, May 11, 2011 at 11:15 AM, Steve Klabnik <steve@steveklabnik.com> wrote:
If you've never contributed to Ruby before, I wrote up this blog post,
explaining just how easy it is for you to add the documentation that Eric's
asking for.
I'm not sure who makes these decisions for ruby-doc.org, but is there any chance that we could get Yardoc-formatted documentation (or at least a fresh stylesheet for standard rdoc output) this time around?
I'd be very inclined to help out with this effort if I knew the output was going to look fresh and appealing.
(Yes, I know I could host my own styled version of the docs. But I'm talking about what comes up first on Google.)
Cheers,
David
···
On Wednesday, 11 May 2011 at 7:25 am, jake kaiden wrote:
this is certainly a worthwhile effort - thanks for organizing it...
happy to help out in any way i can.
- 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.
I can't speak for Eric, but I think part of documenting is marking the code which does not need documenting with :nodoc:
- 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?
- 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.
# 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.
···
On Jun 15, 2011, at 9:23 AM, Markus Fischer wrote:
I would appreciate this more for the fact that the syntax is better.
···
On Wed, May 11, 2011 at 14:32, David Jacobs <developer@wit.io> wrote:
I'm not sure who makes these decisions for ruby-doc.org, but is there any chance that we could get Yardoc-formatted documentation (or at least a fresh stylesheet for standard rdoc output) this time around?
I'd be very inclined to help out with this effort if I knew the output was going to look fresh and appealing.
- 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.
I can't speak for Eric, but I think part of documenting is marking the
code which does not need documenting with :nodoc:
But rdoc, at least by default, does not document private methods. I
assume it's just a limitation of the coverage tool for now.
Thanks, I quickly noticed it contains stdlib but not core.
I'm still looking for a convenient way to quickly search through the
current docs. Currently I use a FF4 keyworded search which uses the
integrated search on ruby-doc.org :
The results I get back when I search for e.g. split or other methods are
often nearly perfect. That's where I also found Addrinfo.
The advantage at ruby-doc, at least for me, is that it includes core;
and I need core too.
That too, but I figured if the goal here was to complete the documentation (instead of revamping it), a complete conversion to Yardoc would be a hard sell. (If that's not the case, I'll be thrilled.)
···
On Wednesday, 11 May 2011 at 8:53 am, Nikolai Weibull wrote:
On Wed, May 11, 2011 at 14:32, David Jacobs <developer@wit.io> wrote:
> I'm not sure who makes these decisions for ruby-doc.org, but is there any chance that we could get Yardoc-formatted documentation (or at least a fresh stylesheet for standard rdoc output) this time around?
>
> I'd be very inclined to help out with this effort if I knew the output was going to look fresh and appealing.
I would appreciate this more for the fact that the syntax is better.
When you run `make` on ruby trunk rdoc is run with --all so private methods are picked up. The coverage report does the same.
···
On Jun 17, 2011, at 2:12 AM, Markus Fischer wrote:
On 16.06.2011 23:55, Justin Collins wrote:
Markus Fischer wrote:
- 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.
I can't speak for Eric, but I think part of documenting is marking the
code which does not need documenting with :nodoc:
But rdoc, at least by default, does not document private methods. I
assume it's just a limitation of the coverage tool for now.
