RDoc vs metaprogramming

[Pau Garcia i Quiles]

--nextPart10191233.7Aucc0r5lq
Content-Type: text/plain;
charset="iso-8859-15"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

Hello,

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

class XSPFBlah
=20
attributes =3D %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=20
useless. Is there anything I could do to get RDoc to work?

Thank you.

=2D-=20
Pau Garcia i Quiles
http://www.elpauer.org
(Due to the amount of work, I usually need 10 days to answer)

--nextPart10191233.7Aucc0r5lq
Content-Type: application/pgp-signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)

iD8DBQBFMa+f/DzYv9iGJzsRAjqNAKDfE1rHNBoOBQuEiN0VjY009ocStgCffxJg
I11GSPvha3KygBrcoM9GPQc=
=Ga3d
-----END PGP SIGNATURE-----

--nextPart10191233.7Aucc0r5lq--

 

[ara.t.howard]

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.

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

 

[Eric Hodel]

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.

 

[Ryan Davis]

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]

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

 

[Pau Garcia i Quiles]

--nextPart1318559.0mBE9arWZN
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

=20
On Oct 14, 2006, at 8:48 PM, Pau Garcia i Quiles wrote:
=20
=20
I don't know what XSPF is so this might be a terribly ignorant =20
question... but... what value do you get from having a bunch of =20
redundant documentation for methods that presumably do mostly the =20
same thing across the board? Which is worse, zero useless =20
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=20
specification to the rdoc, i. e. when you use track.duration, by reading th=
e=20
rdoc, you know you are getting milliseconds and you don't need to go to the=
=20
XSPF spec to know if that number are milliseconds or seconds; when you use=
=20
playlist.meta you know you are receiving an array, etc

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

=2D-=20
Pau Garcia i Quiles
http://www.elpauer.org
(Due to the amount of work, I usually need 10 days to answer)

--nextPart1318559.0mBE9arWZN
Content-Type: application/pgp-signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)

iD8DBQBFMmyT/DzYv9iGJzsRAi1tAKC6Bhl4CsJ7zMez+T4qI83YkHsHjQCg70cE
IJIPFDD4o1fpGsmOt7eBaVE=
=aPqh
-----END PGP SIGNATURE-----

--nextPart1318559.0mBE9arWZN--

 

[Ken Bloom]

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