Metaprogramming and rdoc

Ruby
1

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.

2

Hans F. wrote:

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.

My first guess(es) would be:

  • document the functionality in your class documentation
    AND/OR
  • use/write a code generator to generate rdoc-able ruby code with the
    method annotations as the method comments in the outputted ruby code,
    which would be picked up by rdoc

Zach

3

On Thu, 17 Nov 2005, Hans Fugal wrote:

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.

put a hook into your methods that spews out a docstring into a file.
run your
tests, then run rdoc over this file. take the hook out.

another approach

doccumentation

def meta_methods
# empty
end

-a

4

Hans F. wrote:

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.