From: Joel VanderWerf <vjoel@...>
Date: 2005-11-17T06:09:03+09:00
Subject: Re: Metaprogramming and rdoc

Hans Fugal wrote:
> I find myself metaprogramming in ruby more and more. I think this is a
> good thing. It also has the unfortunate side effect of pitting me
> against my old friend rdoc. I want to document the methods, but rdoc
> has no clue that they even exist. Is there some middle ground, or must
> one just put it in the class's blurb, or give in to not
> metaprogramming?
> 
> A simple example:
> 
> Class Foo
>   # Methods that do just about the same thing
>   %w{foo bar baz quux}.each do |m|
>     eval "def #{m}(*args); something_interesting(m.to_sym,*args); end"
>   end
> end
> 
> Rdoc of course knows nothing, but I may have something interesting to
> say about this group of methods as a whole.
> 

This won't help with programmatically generating rdoc comments, if
that's what you want. But:

* define a class method ("my_interesting_accessor") that does your eval

* call the class method separately for each of foo bar .... (a little
more painful than a loop, but you've got to do it anyway if you want to
type out separate documentation for each)

* put docs above each of these as you wish

* use the -A my_interesting_accessor option to rdoc, and it will
recognize these comments

(It's not just for accessors, but that was the original use that I
proposed and Dave implemented. It really works for any class method that
has the same syntax as accessor definitions.)

$ rdoc --help | grep -A2 accessorname | ruby -pe 'sub!(/^ {6,12}/, "")'
--accessor, -A accessorname[,..]
                comma separated list of additional class methods
                that should be treated like 'attr_reader' and
                friends. Option may be repeated. Each accessorname
                may have '=text' appended, in which case that text
                appears where the r/w/rw appears for normal accessors.


-- 
      vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407