# Metaprogramming and rdoc

**URL:** <https://www.ruby-forum.com/t/metaprogramming-and-rdoc/48094>\
**Category:** Ruby\
**Created:** [November 16, 2005, 6:45pm UTC](https://www.ruby-forum.com/t/metaprogramming-and-rdoc/48094 "2005-11-16T18:45:17Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![fugalh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/f/48db29/32.png) [@fugalh](https://www.ruby-forum.com/u/fugalh)\
**Post date:** [November 16, 2005, 6:45pm UTC](https://www.ruby-forum.com/t/metaprogramming-and-rdoc/48094/1 "2005-11-16T18:45:17Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![fugalh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/f/48db29/32.png) [@fugalh](https://www.ruby-forum.com/u/fugalh)\
**Post date:** [November 16, 2005, 6:54pm UTC](https://www.ruby-forum.com/t/metaprogramming-and-rdoc/48094/2 "2005-11-16T18:54:23Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![fugalh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/f/48db29/32.png) [@fugalh](https://www.ruby-forum.com/u/fugalh)\
**Post date:** [November 16, 2005, 7:24pm UTC](https://www.ruby-forum.com/t/metaprogramming-and-rdoc/48094/3 "2005-11-16T19:24:32Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![fugalh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/f/48db29/32.png) [@fugalh](https://www.ruby-forum.com/u/fugalh)\
**Post date:** [November 16, 2005, 10:10pm UTC](https://www.ruby-forum.com/t/metaprogramming-and-rdoc/48094/4 "2005-11-16T22:10:48Z")

</div>

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.