[ruby-talk:01539] Re: Ruby library modules and documentation

[posted to comp.lang.ruby]

Dave Thomas wrote:
> 
> Well, the time has come to start documenting the library modules--the
> stuff until lib/.

Just a couple of thoughts. 

I agree with zaq that one person trying to nail down all of the
documentation for the lib modules is probably a bad idea. Not least
because you will end up hating documenting anything from then on.

I also agree that examples are some of the most powerful ways of
documenting what a module/class does and exploring all the ways of using
it. Trying to come up with neat ways of using a module, just for
documentation purposes doesn't sound like too much fun. What about
getting people to contribute snippets of code from programs they have
created, that shows good use of a module? Include a brief note about
what its doing, why the module is being used and any 'gotchas'. Then
someone like yourself can cobble together a set of documentation that
reflects how people are using the language and doesn't require that you
give yourself a headache trying to explain how to use
ConfusingYetInterestingModule.


Regards,

  Nige

-- 
Nigel Rantor
e-mail - [e-mail]

There is always an easier way to do it.
                       - Wise Words From The Worm