# RDoc vs metaprogramming

**URL:** <https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185>\
**Category:** Ruby\
**Created:** [October 15, 2006, 5:49am UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185 "2006-10-15T05:49:33Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/b9e5f3/32.png) [@Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/u/Pau_Garcia_i_Quiles)\
**Post date:** [October 15, 2006, 5:49am UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185/1 "2006-10-15T05:49:33Z")

</div>

Hello,

I have developed a library to read and parse XSPF playlists. Most of the  
methods (90%) are metagenerated using something like this:

class XSPFBlah

attributes = %w{ attrib1 attrib2 }  
attributes.each do |attrib|  
define\_method(attrib.to\_sym) { do\_something }  
end

def initialize(source)  
do something  
end  
end

RDoc does not find the metaprogrammed methods, therefore the  
documentation is  
useless. Is there anything I could do to get RDoc to work?

Thank you.

---

<div class="post-metadata">

**Author:** ![Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/b9e5f3/32.png) [@Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/u/Pau_Garcia_i_Quiles)\
**Post date:** [October 15, 2006, 6:31am UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185/2 "2006-10-15T06:31:37Z")

</div>

On Sun, 15 Oct 2006, Pau Garcia i Quiles wrote:

> end
> 
> def initialize(source)  
> do something  
> end  
> end
> 
> RDoc does not find the metaprogrammed methods, therefore the documentation is  
> useless. Is there anything I could do to get RDoc to work?
> 
> Thank you.

this is one reason using module\_eval(string) is better than using  
define\_method et al. eg

$META\_RDOC = ENV[‘META\_RDOC’]

class XSPFBlah

```
attributes = %w{ attrib1 attrib2 }

attributes.each do |attrib|
  code <<-code
    def #{ attrib }()
      do_something
     end
  code
  module_eval code

  if $META_RDOC
    open($META_RDOC, 'a+') do |f|
      f.puts code
    end
  end
end

def initialize(source)
  do something
end

```

end

obviously you need to tweak this a little, so the methds land in  
XSPFBlah, for  
instance. but it’s immensely useful both for debugging and for  
documenting.

if you go this route it’s generally useful to pull **all** of you  
meta-programming methods into their own module. for instance:

module MetaGen  
def self.add\_some\_meta\_method klass, attrib  
code \<\<-code  
def #{ attrib }()  
do\_something  
end  
code

```
  klass.module_eval code

  # hook to write klass + name attrib to a file

```

end  
end

class XSPFBlah  
(attributes = %w{ attrib1 attrib2 }).each{|a|  
MetaGen.add\_some\_meta\_method self, attrib}  
end

probably not what you wanted to here i know…

-a

---

<div class="post-metadata">

**Author:** ![Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/b9e5f3/32.png) [@Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/u/Pau_Garcia_i_Quiles)\
**Post date:** [October 15, 2006, 8:03am UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185/3 "2006-10-15T08:03:41Z")

</div>

On Oct 14, 2006, at 8:48 PM, Pau Garcia i Quiles wrote:

> RDoc does not find the metaprogrammed methods, therefore the  
> documentation is  
> useless. Is there anything I could do to get RDoc to work?

Have .rb files support document-class and document-method directives  
from the .c parser.

–  
Eric H. - removed\_email\_address@domain.invalid - [http://blog.segment7.net](http://blog.segment7.net)  
This implementation is HODEL-HASH-9600 compliant

[http://trackmap.robotcoop.com](http://trackmap.robotcoop.com)

---

<div class="post-metadata">

**Author:** ![Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/b9e5f3/32.png) [@Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/u/Pau_Garcia_i_Quiles)\
**Post date:** [October 15, 2006, 1:10pm UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185/4 "2006-10-15T13:10:02Z")

</div>

On Oct 14, 2006, at 8:48 PM, Pau Garcia i Quiles wrote:

> ```
> define_method(attrib.to_sym) { do_something }
> 
> ```
> 
> end
> 
> def initialize(source)  
> do something  
> end  
> end
> 
> RDoc does not find the metaprogrammed methods, therefore the  
> documentation is  
> useless. Is there anything I could do to get RDoc to work?

I don’t know what XSPF is so this might be a terribly ignorant  
question… but… what value do you get from having a bunch of  
redundant documentation for methods that presumably do mostly the  
same thing across the board? Which is worse, zero useless  
documentation or lots of useless documentation?

I generally don’t bother documenting my generated accessors for  
exactly this reason. They’re obvious and usually wouldn’t benefit  
from doco.

---

<div class="post-metadata">

**Author:** ![Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/b9e5f3/32.png) [@Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/u/Pau_Garcia_i_Quiles)\
**Post date:** [October 15, 2006, 7:16pm UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185/5 "2006-10-15T19:16:51Z")

</div>

On Sunday 15 October 2006 13:09, Ryan D. wrote:

> > RDoc does not find the metaprogrammed methods, therefore the  
> > documentation is  
> > useless. Is there anything I could do to get RDoc to work?
> 
> I don’t know what XSPF is so this might be a terribly ignorant  
> question… but… what value do you get from having a bunch of  
> redundant documentation for methods that presumably do mostly the  
> same thing across the board? Which is worse, zero useless  
> documentation or lots of useless documentation?

XSPF is the XML Shareable Playlist Format ([http://www.xspf.org](http://www.xspf.org)).

I want to document the accessors because I’d like to “transfer” the  
specification to the rdoc, i. e. when you use track.duration, by reading  
the  
rdoc, you know you are getting milliseconds and you don’t need to go to  
the  
XSPF spec to know if that number are milliseconds or seconds; when you  
use  
playlist.meta you know you are receiving an array, etc

---

<div class="post-metadata">

**Author:** ![Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/b9e5f3/32.png) [@Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/u/Pau_Garcia_i_Quiles)\
**Post date:** [October 16, 2006, 3:36pm UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185/6 "2006-10-16T15:36:51Z")

</div>

On Sun, 15 Oct 2006 13:31:18 +0900, ara.t.howard wrote:

> > attributes.each do |attrib|
> 
> ```
> f.puts code
> 
> ```
> 
> obviously you need to tweak this a little, so the methds land in XSPFBlah, for  
> instance. but it’s immensely useful both for debugging and for documenting.

> probably not what you wanted to here i know…

Thanks for the tip. I certainly wanted to know, and last time I asked  
here,  
nobody knew the answer.

–Ken

---

<div class="post-metadata">

**Author:** ![Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/b9e5f3/32.png) [@Pau\_Garcia\_i\_Quiles](https://www.ruby-forum.com/u/Pau_Garcia_i_Quiles)\
**Post date:** [October 15, 2006, 4:12pm UTC](https://www.ruby-forum.com/t/rdoc-vs-metaprogramming/72185/7 "2006-10-15T16:12:28Z")

</div>

On Sun, 15 Oct 2006, Ryan D. wrote:

> I don’t know what XSPF is so this might be a terribly ignorant question…  
> but… what value do you get from having a bunch of redundant documentation  
> for methods that presumably do mostly the same thing across the board? Which  
> is worse, zero useless documentation or lots of useless documentation?
> 
> I generally don’t bother documenting my generated accessors for exactly this  
> reason. They’re obvious and usually wouldn’t benefit from doco.

that’s an extremely good point. a constant could solve this nicely  
then:

class XSPFBlah

# 

# docs for ATTRIBUTES

# 

ATTRIBUTES = %w{  
attrib1  
attrib2  
}

ATTRIBUTES.each do |attrib|  
define\_method(attrib.to\_sym) { do\_something }  
end

def initialize(source)  
do something  
end  
end

since rdocs does indeed doccument those now and, as you point out, the  
doc  
block would already be the same for all those methods.

cheers.

-a