Ruby 1.9.3 documentation challenge

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

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.

http://blog.steveklabnik.com/contributing-to-rubys-documentation

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

On Wed, May 11, 2011 at 11:15 AM, Steve K. [email protected]
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.

http://blog.steveklabnik.com/contributing-to-rubys-documentation

Cool!


Twitter: @ghosTM55
Facebook.com/ghosThomas

Mechanism, not policy

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

  • j

On Wed, May 11, 2011 at 14:32, David J. [email protected] 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.

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

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

There is currently a discussion on Redmine about switching to YARD:
http://redmine.ruby-lang.org/issues/4211

Markus F. 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:

  • 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

Content preview: On 16.06.2011 23:55, Justin C. 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: […]

Content analysis details: (-2.9 points, 5.0 required)

pts rule name description



-1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]
X-Cloudmark-Analysis: v=1.1
cv=HQ3F56nxkum+cgCiDL7AXQpbvw7DWrWCBJRnYYnM0Zc= c=1 sm=0
a=CPlwVjms4CEA:10 a=rDlpkb2S-8kA:10 a=IkcTkHD0fZMA:10 a=CH-RE0sgAAAA:8
a=dpcX-2CAAAAA:8 a=y3b3jT8EjhXMX-GLqS4A:9 a=QEXdDO2ut3YA:10
a=wPposIssD2IA:10 a=-w7TLmJE7m8A:10 a=VFu7tLI1AyYA:10
a=HpAAvcLHHh0Zw7uRqdWCyQ==:117
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk
Lines: 32
List-Id: ruby-talk.ruby-lang.org
List-Software: fml [fml 4.0.3 release (20011202/4.0.3)]
List-Post: mailto:[email protected]
List-Owner: mailto:[email protected]
List-Help: mailto:[email protected]?body=help
List-Unsubscribe: mailto:[email protected]?body=unsubscribe
Received-SPF: none (Address does not pass the Sender Policy Framework)
SPF=FROM;
[email protected];
remoteip=::ffff:221.186.184.68;
remotehost=carbon.ruby-lang.org;
helo=carbon.ruby-lang.org;
receiver=eq4.andreas-s.net;

On 16.06.2011 23:55, Justin C. wrote:

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

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%3Awnccv6st5qk&q=%s&cof=FORID%3A9

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

On Jun 17, 2011, at 11:12 AM, Markus F. wrote:

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.

It does, actually. It’s a bit hidden under “stdlib” => “core”. :slight_smile:

Regards,
Florian

Content preview: On 17.06.2011 11:30, Florian G. wrote: >> Thanks,
I quickly
noticed it contains stdlib but not core. > > It does, actually. It’s
a bit
hidden under “stdlib” => “core”. :slight_smile: Thanks :slight_smile: […]

Content analysis details: (-2.9 points, 5.0 required)

pts rule name description



-1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]
X-Cloudmark-Analysis: v=1.1
cv=HQ3F56nxkum+cgCiDL7AXQpbvw7DWrWCBJRnYYnM0Zc= c=1 sm=0
a=CPlwVjms4CEA:10 a=rDlpkb2S-8kA:10 a=IkcTkHD0fZMA:10
a=z4coldwSh4F5qiqvATIA:9 a=QEXdDO2ut3YA:10
a=HpAAvcLHHh0Zw7uRqdWCyQ==:117
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk
Lines: 6
List-Id: ruby-talk.ruby-lang.org
List-Software: fml [fml 4.0.3 release (20011202/4.0.3)]
List-Post: mailto:[email protected]
List-Owner: mailto:[email protected]
List-Help: mailto:[email protected]?body=help
List-Unsubscribe: mailto:[email protected]?body=unsubscribe
Received-SPF: none (Address does not pass the Sender Policy Framework)
SPF=FROM;
[email protected];
remoteip=::ffff:221.186.184.68;
remotehost=carbon.ruby-lang.org;
helo=carbon.ruby-lang.org;
receiver=eq4.andreas-s.net;

On 17.06.2011 11:30, Florian G. wrote:

Thanks, I quickly noticed it contains stdlib but not core.

It does, actually. It’s a bit hidden under “stdlib” => “core”. :slight_smile:

Thanks :slight_smile:

Content preview: 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 […]

Content analysis details: (-2.9 points, 5.0 required)

pts rule name description



-1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]
X-Cloudmark-Analysis: v=1.1
cv=vUpxTctd+kpWCBtSXXIkt5ll4Z8E5Qu9nLREXC/hfIo= c=1 sm=0
a=CPlwVjms4CEA:10 a=rDlpkb2S-8kA:10 a=IkcTkHD0fZMA:10 a=mTVtM7KMAAAA:8
a=CH-RE0sgAAAA:8 a=fe4Du_4jg87Tw7NL8d8A:9 a=z9gbKKUCDM2zmKH0F90A:7
a=QEXdDO2ut3YA:10 a=WIphuvhjV2sA:10 a=HpAAvcLHHh0Zw7uRqdWCyQ==:117
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk
Lines: 50
List-Id: ruby-talk.ruby-lang.org
List-Software: fml [fml 4.0.3 release (20011202/4.0.3)]
List-Post: mailto:[email protected]
List-Owner: mailto:[email protected]
List-Help: mailto:[email protected]?body=help
List-Unsubscribe: mailto:[email protected]?body=unsubscribe
Received-SPF: none (Address does not pass the Sender Policy Framework)
SPF=FROM;
[email protected];
remoteip=::ffff:221.186.184.68;
remotehost=carbon.ruby-lang.org;
helo=carbon.ruby-lang.org;
receiver=eq4.andreas-s.net;

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

On Jun 15, 2011, at 9:23 AM, Markus F. wrote:

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 17, 2011, at 2:12 AM, Markus F. wrote:

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.

Content preview: On 15.06.2011 18:23, Markus F. 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. […]

Content analysis details: (-2.9 points, 5.0 required)

pts rule name description



-1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]
X-Cloudmark-Analysis: v=1.1
cv=HQ3F56nxkum+cgCiDL7AXQpbvw7DWrWCBJRnYYnM0Zc= c=1 sm=0
a=CPlwVjms4CEA:10 a=rDlpkb2S-8kA:10 a=IkcTkHD0fZMA:10 a=w2PP7KgtAAAA:8
a=hPOO5x_7WQ7bVIdFsboA:9 a=Tqsi6l-SR2mjwo_FlSwA:7 a=QEXdDO2ut3YA:10
a=HpAAvcLHHh0Zw7uRqdWCyQ==:117
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk
Lines: 8
List-Id: ruby-talk.ruby-lang.org
List-Software: fml [fml 4.0.3 release (20011202/4.0.3)]
List-Post: mailto:[email protected]
List-Owner: mailto:[email protected]
List-Help: mailto:[email protected]?body=help
List-Unsubscribe: mailto:[email protected]?body=unsubscribe
Received-SPF: none (Address does not pass the Sender Policy Framework)
SPF=FROM;
[email protected];
remoteip=::ffff:221.186.184.68;
remotehost=carbon.ruby-lang.org;
helo=carbon.ruby-lang.org;
receiver=eq4.andreas-s.net;

On 15.06.2011 18:23, Markus F. 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.

Question answered:
http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/lib/csv.rb?r1=32141&r2=32140&pathrev=32141

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs