Metaprogramming and rdoc

[Hans Fugal]

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.

 

[Zach Dennis]

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.

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

 

[Ara.T.Howard]

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.

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
--
===============================================================================
| ara [dot] t [dot] howard [at] gmail [dot] com
| all happiness comes from the desire for others to be happy. all misery
| comes from the desire for oneself to be happy.
| -- bodhicaryavatara
===============================================================================

 

[Joel VanderWerf]

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.