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

On Sat, Jun 08, 2002 at 05:17:25PM +0900, Patrick May wrote:
> > 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,
> I noticed that in my practice, test_method would often contain the
> best example code, while the edge cases would be in
> test_method_does_something.

Yes, that happens to me too in many cases but there are some methods
with more varied response whose core behaviour needs more than one
test (think multi dispatch).

> > Of course nobody aims guns if done otherwise :-), but through time
> > I've found that practice to really help.
> With an explicit directive, you could still pull these other bits in
> as examples.  I noticed this naming pattern among the tests that made
> the best examples.
> 
> I guess the question would be "does anyone else have this pattern?"

Sounds like there are many options.  One where everything is in the code:


class TestDatabase < Test::Unit::TestCase 
  def test_foo
    ...
  end

  def test_foo_invalid_parameter_raises   
    ...
  end
end


The name of the test class tells in the documentation for which class
these tests should go.  test_foo generates the first (and most
relevant) example for the method foo,
test_foo_invalid_parameter_raises generates another example for the
method foo, as well as any test_foo_xxxxxxxx.

Then explicit directives could integrate or completely take the place
of implicit directives:


class TestUnnamed < Test::Unit::TestCase
  # :testing: Database

  def test_foo_irrelevant_test
    # :nodoc:
  end

  def test_not_following_the_pattern
    # :testing: foo
  end
end


Anyway, this is just speculation.  Dave seemed to see merit in the
idea of tests in documentation, and I'm pretty sure that he will come
up with the optimal solution.  He has done before. :-)

> P.S. I had problems looking up [ruby-talk:22920]
> 
> http://www.ruby-talk.com/cgi-bin/scat.rb/ruby/ruby-talk/22920
> 
> seems to point to [ruby-talk:23457] ?

Sorry, can't help on that, but I'll forward you the 22920.

Massimiliano