RDoc vs metaprogramming

Ruby
1

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.

2

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

3

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. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

4

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.

5

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).

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

6

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

7

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