From: Massimiliano Mirra <list@...>
Date: 2002-06-08T06:16:28+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

On Sat, Jun 08, 2002 at 05:16:38AM +0900, Patrick May wrote:
> class TestApple < RUNIT::TestCase
>     # divide into even portions for the kids
>     def test_slice
>         ...
>     end
> end
> 
> "divide..." becomes an rdoc comment for anApple.slice.  The text of
> test_slice gets linked as an example.

See comments by Nat Price in [ruby-talk:22920] about meaningful test
names.  Basically a test should be named in such a way that, when the
runner reports it as failing, one can get an idea of what is failing
by just peeking at the name, e.g. not just a single test_divide but
test_divide_raises_if_by_zero,
test_divide_returns_correct_result_with_nonzero, etc.

Of course nobody aims guns if done otherwise :-), but through time
I've found that practice to really help.

Massimiliano