[RDoc etc] automatic documentation: using tests in addition to / instead of comments

ruby-talk
1

Upon reflection, I saw two points throughout this discussion:

  • it is good to keep the classes as light as possible, so that
    refactoring / etc. is not hindered.
  • it would be good if the unit tests could appear as ‘examples’ in the
    documentation.

Then a third idea rolled up:

  • would it be good if all the documentation was encoded in the unit
    tests?

unit tests are expectations of your code, like documentation. It
might be good to put them together…

Dave Thomas Dave@PragmaticProgrammer.com wrote in message news:m2d6vp74hs.fsf@zip.local.thomases.com…

  1. A convention which, if followed, allows RDoc to find the tests
    automatically.

Perhaps a naming convention be used in the links. i.e,

class TestApple < RUNIT::TestCase
# divide into even portions for the kids
def test_slice
…
end
end

class Apple
def slice
…
end
end

“divide…” becomes an rdoc comment for anApple.slice. The text of
test_slice gets linked as an example.

I think this type of convention could be made flexible enough to work
with most coding styles (camelCase test methods versus
using_underscore, etc.)

On the other hand, I bet you’ve already past this point. Sometimes, I
don’t even know why I post to this list, b/c I just get pointed to
ruby talk < 10000 :slight_smile:

good day,

~ Patrick

2

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

···

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.

3

And 22920 > 10000. :slight_smile:

Paul

···

On Sat, Jun 08, 2002 at 06:16:28AM +0900, Massimiliano Mirra wrote:

On Sat, Jun 08, 2002 at 05:16:38AM +0900, Patrick May wrote:

On the other hand, I bet you’ve already past this point. Sometimes,
I don’t even know why I post to this list, b/c I just get pointed to
ruby talk < 10000 :slight_smile:

See comments by Nat Price in [ruby-talk:22920] about meaningful test

4

Massimiliano Mirra list@chromatic-harp.com wrote in message news:20020607211650.GA6102@prism.localnet…

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.

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.

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?”

~ Patrick

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] ?

5

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. :slight_smile:

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

···

On Sat, Jun 08, 2002 at 05:17:25PM +0900, Patrick May wrote: