Ruby 1.9.3 documentation challenge

E

Eric Hodel

With the freeze of Ruby 1.9.3 coming up near the end of the month I =
looked at how much documentation coverage ruby has for it's standard =
library:

Files: 511

Classes: 1036 ( 624 undocumented)
Modules: 228 ( 136 undocumented)
Constants: 1335 (1134 undocumented)
Attributes: 738 ( 381 undocumented)
Methods: 8098 (2960 undocumented)

Total: 11435 (5235 undocumented)
54.22% documented

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:

http://bit.ly/ruby-1-9-3-docs-challenge

Let's make Ruby 1.9.3 the best-documented release ever!=
 
H

Hashmal

Thanks! I never really contributed to Ruby, but if it's that easy I'll
probably do so.
 
J

jake kaiden

this is certainly a worthwhile effort - thanks for organizing it...
happy to help out in any way i can.

- j
 
D

David Jacobs

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
 
N

Nikolai Weibull

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

David Jacobs

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

Markus Fischer

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
 
J

Justin Collins

Markus said:
- 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?


Ever since 1.9 came out, I've felt like ruby-doc.org has fallen behind.
rdoc.info has been my go-to site for documentation:
http://rdoc.info/stdlib/socket/1.9.2/Addrinfo:initialize


-Justin
 
M

Markus Fischer

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.
Ever since 1.9 came out, I've felt like ruby-doc.org has fallen behind.
rdoc.info has been my go-to site for documentation:
http://rdoc.info/stdlib/socket/1.9.2/Addrinfo:initialize

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 :

http://www.ruby-doc.org/search.html?cx=011815814100681837392:wnccv6st5qk&q=%s&cof=FORID:9

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.

- Markus
 
E

Eric Hodel

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

Eric Hodel

=20
But rdoc, at least by default, does not document private methods. I
assume it's just a limitation of the coverage tool for now.

When you run `make` on ruby trunk rdoc is run with --all so private =
methods are picked up. The coverage report does the same.=
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,479
Members
44,899
Latest member
RodneyMcAu

Latest Threads

Top