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

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

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

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

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

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

--nextPart1318559.0mBE9arWZN--