RDoc vs metaprogramming

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.elpauer.org
(Due to the amount of work, I usually need 10 days to answer)

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

···

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.

--
my religion is very simple. my religion is kindness. -- the dalai lama

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

···

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?

--
Eric Hodel - drbrain@segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

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.

···

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?

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

class XSPFBlah

···

On Sun, 15 Oct 2006, Ryan Davis 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.

#
# 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
--
my religion is very simple. my religion is kindness. -- the dalai lama

> 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://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

···

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

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

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.elpauer.org
(Due to the amount of work, I usually need 10 days to answer)

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

--Ken

···

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

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