From: Dave Thomas <Dave@...>
Date: 2002-07-23T05:49:33+09:00
Subject: Re: rdtool and rdoc

"Lyle Johnson" <jlj@cfdrc.com> writes:

> Guy, are you against using RDoc to document the libraries and the
> interpreter, or just against using it to document the interpreter?
> If the latter, I would agree with you that for the most part RDoc
> might not be the best way to document the interpreter's
> internals. It could be useful for documenting the built-in classes,
> however.

One reason you might want to consider it is simply the ease of keeping
documentation up to date. For example, in imlib.c, there's:

     /*
      * Returns a new Imlib2::Color::RgbaColor.
      *
      * Examples:
      *   r, g, b, a = 255, 0, 0, 255
      *   border = Imlib2::Color::RgbaColor.new r, g, b, a
      *
      *   values = [255, 0, 0, 255]
      *   border = Imlib2::Color::RgbaColor.new values
      *
      */
     VALUE rgba_color_new(int argc, VALUE *argv, VALUE klass) {
       Imlib_Color *color;
       VALUE c_o;

       color = malloc(sizeof(Imlib_Color));
       memset(color, 0, sizeof(Imlib_Color));

       c_o = Data_Wrap_Struct(klass, 0, free, color);
       rb_obj_call_init(c_o, argc, argv);

       return c_o;
     }

  ...

      rb_define_singleton_method(cRgbaColor, "new", rgba_color_new, -1);


That's enough to et RDoc use the comment block as the documentation
for the class' constructor.

Now say you decide to change the method. With the comment right there
next to the implementaton, it's easy to remember to update it. If it's
in a separate file, it'll get left behind. Maybe...  :)



Cheers


Dave