From: ara.t.howard@...
Date: 2006-01-13T06:07:15+09:00
Subject: Re: Design contracts and refactoring (was Re: mathn: ugly warnings)

On Fri, 13 Jan 2006, James Britt wrote:

> ara.t.howard@noaa.gov wrote:
> ...
>
>> admittedly this is only a step up from saying 'read the unit test', but the
>> higher level and shortness of sample programs does make it a step up.
>> also, the sample programs can progress in complexity in such a way to teach
>> the user in a nice way.
>
> But what will the user see from ri and rdoc?

nothing.  i've found myself using them less and less - at this point i use
them about once per month.  my feeling is that

   vi -o samples/*

is much more powerful.

when considering all the libraries i've released i get the fewest question and
most bug fixes not from the documented ones - but the the ones with the most
samples.

i realize my view will be in the minority and that some projects simple cannot
fit into this box.  in any case, it's my person opinion that testable samples
are a huge benefit to library maintainers and users and that, except for very
large and complex systems, really do serve quite well as documentation.

my intent in posting this, btw, was just to bring attention to the fact that
i've found it useful and people who love docs and unit tests might consider it
as another weapon.

cheers.

-a
-- 
strong and healthy, who thinks of sickness until it strikes like lightning?
preoccupied with the world, who thinks of death, until it arrives like
thunder?  -- milarepa