Asp Forum - RDoc vs metaprogramming

Pau Garcia i Quiles

10/15/2006 3:49:00 AM

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.

--
Pau Garcia i Quiles
http://www.e...
(Due to the amount of work, I usually need 10 days to answer)

6 Answers

Ara.T.Howard

10/15/2006 4:31:00 AM

Eric Hodel

10/15/2006 6:03:00 AM

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 Hodel - drbrain@segment7.net - http://blog.se...
This implementation is HODEL-HASH-9600 compliant

http://trackmap.rob...

Ryan Davis

10/15/2006 11:10:00 AM

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

> 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?

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.

Ara.T.Howard

10/15/2006 2:11:00 PM

Pau Garcia i Quiles

10/15/2006 5:15:00 PM

On Sunday 15 October 2006 13:09, Ryan Davis wrote:

>
> On Oct 14, 2006, at 8:48 PM, Pau Garcia i Quiles wrote:
>
> > 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?
>
> 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://ww...).

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

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

--
Pau Garcia i Quiles
http://www.e...
(Due to the amount of work, I usually need 10 days to answer)

Ken Bloom

10/16/2006 1:30:00 PM

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

> On Sun, 15 Oct 2006, Pau Garcia i Quiles wrote:
>
>> 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.
>
> 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.
>

> 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

--
Ken Bloom. PhD candidate. Linguistic Cognition Laboratory.
Department of Computer Science. Illinois Institute of Technology.
http://www.iit.edu...
I've added a signing subkey to my GPG key. Please update your keyring.

comp.lang.ruby

RDoc vs metaprogramming

Pau Garcia i Quiles

Ara.T.Howard

Eric Hodel

Ryan Davis

Ara.T.Howard

Pau Garcia i Quiles

Ken Bloom

x Login to ForumsZone