Ruby 1.9.3 documentation challenge

Discussion in 'Ruby' started by Eric Hodel, May 10, 2011.

  1. Eric Hodel

    Eric Hodel Guest

    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!=
    Eric Hodel, May 10, 2011
    #1
    1. Advertising

  2. Steve Klabnik, May 11, 2011
    #2
    1. Advertising

  3. Eric Hodel

    Hashmal Guest

    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.
    >
    > http://blog.steveklabnik.com/contributing-to-rubys-documentation
    Hashmal, May 11, 2011
    #3
  4. Eric Hodel

    Thomas Yao Guest

    On Wed, May 11, 2011 at 11: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.
    >
    > http://blog.steveklabnik.com/contributing-to-rubys-documentation


    Cool!

    --
    Twitter: @ghosTM55
    Facebook.com/ghosThomas

    Mechanism, not policy
    Thomas Yao, May 11, 2011
    #4
  5. Eric Hodel

    jake kaiden Guest

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

    - j

    --
    Posted via http://www.ruby-forum.com/.
    jake kaiden, May 11, 2011
    #5
  6. Eric Hodel

    David Jacobs Guest

    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.
    >
    > - j
    >
    > --
    > Posted via http://www.ruby-forum.com/.
    >
    David Jacobs, May 11, 2011
    #6
  7. On Wed, May 11, 2011 at 14:32, David Jacobs <> 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.
    Nikolai Weibull, May 11, 2011
    #7
  8. Eric Hodel

    David Jacobs Guest

    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 <> 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.
    >
    David Jacobs, May 11, 2011
    #8
  9. Steve Klabnik, May 11, 2011
    #9
  10. 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
    Markus Fischer, Jun 15, 2011
    #10
  11. 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:

    > - 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
    Justin Collins, Jun 16, 2011
    #11
  12. 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.

    > 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
    Markus Fischer, Jun 17, 2011
    #12
  13. On Jun 17, 2011, at 11:12 AM, Markus Fischer 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". :)

    Regards,
    Florian
    Florian Gilcher, Jun 17, 2011
    #13
  14. On 17.06.2011 11:30, Florian Gilcher wrote:
    >> Thanks, I quickly noticed it contains stdlib but not core.

    >
    > It does, actually. It's a bit hidden under "stdlib" => "core". :)


    Thanks :)
    Markus Fischer, Jun 17, 2011
    #14
  15. Markus Fischer, Jun 17, 2011
    #15
  16. Eric Hodel

    Eric Hodel Guest

    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:
    >=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.=
    Eric Hodel, Jun 17, 2011
    #16
  17. Eric Hodel

    Eric Hodel Guest

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

    >>=20
    >> I can't speak for Eric, but I think part of documenting is marking =

    the
    >> code which does not need documenting with :nodoc:

    >=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.=
    Eric Hodel, Jun 18, 2011
    #17
    1. Advertising

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

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Cameron Laird
    Replies:
    1
    Views:
    654
    Josiah Carlson
    Apr 3, 2004
  2. Kenneth McDonald
    Replies:
    2
    Views:
    729
  3. Replies:
    1
    Views:
    1,211
    Andy Dingley
    Sep 16, 2006
  4. Brett S Hallett

    Secure Ruby - second challenge !

    Brett S Hallett, Dec 17, 2003, in forum: Ruby
    Replies:
    4
    Views:
    114
  5. Pit Capitain

    Ruby Challenge

    Pit Capitain, May 11, 2005, in forum: Ruby
    Replies:
    8
    Views:
    167
    Pit Capitain
    May 12, 2005
Loading...

Share This Page