From: Dave Thomas <Dave@...>
Date: 2002-03-27T07:28:37+09:00
Subject: Re: ruby-dev summary 16301-16500

Minero Aoki <aamine@mx.edit.ne.jp> writes:

>   These libraries will be added in Ruby 1.7 branch:

At the risk of appearing pushy, I'm wondering if we could also look at
making RDoc a standard part of the distribution. It seems to have been
shaken down now, so I'm going to be taking it out of alpha. There
would be major benefits to having a single style for documenting Ruby,
both extensions and .rb files.

On a related note. As RDoc handles .c extensions, and seems pretty
happy parsing the Ruby interpreter's source, how about a small project
to integrate the 'ri' documentation with the Ruby source itself? This
would have a couple of significant advantages:

1. The documentation would be close to the implementation, so people
   could see what code is supposed to do.

2. The documentation would be more likely to be up-to-date. As people
   change functionality, or as they add new functionality, the
   documentation could be easily updated.

3. Eventually, RDoc will support documentation databases, integrating
   documentation from multiple sources into a single unified structure
   on a user's box. Having the Ruby core itself documented this way
   means that a class that derives from (say) Hash will be linked in
   to Hash's own documentation.

In practice, this means associating an RDoc-format comment block with
the C function that implements each Ruby library method. For example,
here's a couple of methods from range.c:

     /*  Range.new( start, end, exclusive=false ) -> aRange 
      *  ----
      *  Constructs a range using the given start and end. If the third 
      *  parameter is omitted or is false, the range will include the end 
      *  object; otherwise, it will be excluded. 
      */

     static VALUE
     range_initialize(argc, argv, obj)
         int argc;
         VALUE *argv;
         VALUE obj;
     {
         VALUE beg, end, flag;

         rb_scan_args(argc, argv, "21", &beg, &end, &flag);
         /* Ranges are immutable, so that they should be initialized only once. */
         if (rb_ivar_defined(obj, id_beg)) {
             rb_raise(rb_eNameError, "`initialize' called twice");
         }
         range_init(obj, beg, end, RTEST(flag));
         return Qnil;
     }

     /*
      * rng.exclude_end? -> true or false
      * -----
      * Returns true if rng excludes its end value.
      */

     static VALUE
     range_exclude_end_p(range)
         VALUE range;
     {
         return EXCL(range)?Qtrue:Qfalse;
     }


As a community, we could do this very simply. I could produce a set of
comment blocks in RDoc format by hacking a new version of
RI. Volunteers could then take individual .c files and add these
comments at the correct place, sending the results back to someone for
checking and integration back into the CVS tree. We could do it in a
day or two. All it would take would be enough volunteers and matz's
agreement.

Let's discuss this before we start volunteering--we need matz's buy-in
before we do anything.


Cheers


Dave