From: Pau Garcia i Quiles <pgquiles@...>
Date: 2006-10-16T02:15:07+09:00
Subject: Re: RDoc vs metaprogramming

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

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

>=20
> On Oct 14, 2006, at 8:48 PM, Pau Garcia i Quiles wrote:
>=20
> > Hello,
> >
> > I have developed a library to read and parse XSPF playlists. Most =20
> > of the
> > methods (90%) are metagenerated using something like this:
> >
> > class XSPFBlah
> >
> >   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 =20
> > documentation is
> > useless. Is there anything I could do to get RDoc to work?
>=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--