From: benny <listen@...>
Date: 2004-11-26T06:32:57+09:00
Subject: [RDOC] Using unit-tests as examples for a documentation

dear list,

suddenly this idea jumped on my brain:

when using unit tests we got this pretty methods like 
 assert_equal() 
and 
 assert_match()

in which we are telling what we expect to get back from a method.
For this methods we invent more or less realistical examples for 
how we could use the tested method.
We only need to select realistic examples to let them be meaningful and if
they are, they could in fact serve as examples for a documentation as well.

In a similar way we use the "don'ts" -  the prohibited usage of our method
as flesh for the 
 assert_raise()

tests (although I am not sure if negative examples are that useful for a
documentation).

As we all know: in the documentation nothing beats a good example!

Now the idea: Why not use the examples in the unit-tests (at least the
"positive ones") as link to a popup window "examples" in the
HTML-documentation created by rdoc?

For this to work properly we might need a convention for the locations of
the unit-tests (e.g. as given in Progr. RubyV.2, page 159*) and an optional
switch for rdoc to tell it to search for unit-tests and make the examples
for the corresponding methods.

what do you think about it? might that be possible or would there be so much
divergence in the modelling of unit tests that rdoc won't have a chance to
tie that all together?

I see a big advantage coming out of this approach. 
Consider you were using unit-tests anyway on a regular basis. then you would
run them at least anytime you make changes to your old code. so you will
have to fix the unit-tests as well if you do some changes that affect the
usage of your method. once changed the automatically build examples would
be up to date if you are running rdoc the next time. (and even an outdated,
"forgotten" documentation might stay useful when there are working examples
coming with it).

Surely that would affect the way we organize unit-test name parameter
therein etc. but that should not be that bad.


regards, benny

* the example given is:
 
roman
     |-----lib/
     |        |---- roman.rb
     |        |----- other files....
     |----test/
     |        |-----test_roman.rb
     |        |----- other tests......