From: Dave Thomas <Dave@...>
Date: 2002-05-20T22:04:07+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

Tobias Reif <tobiasreif@pinkjuice.com> writes:

> So it could be a great opportunity for a documenting tool
> like RDoc to browse tests and feature their information
> as documentation near the documented methods.

Actually, by an amazing coincidence... :)  That's something we've been
talking about doing. There's a brief hold up while I struggle with a
philosophical question.

In (say) Java, people tend to keep the unit tests in separate files. I
think this is for two reasons. First the tests add bulk to the class
files. Second, the additional verbiage in Java means the tests obscure
the meaning of the code.

Neither of these apply to Ruby, and yet we still tend to put the unit
tests in a separate file. So I'm wondering what happens it we break
that tradition:

   
   class Multiplier

      test :numeric, "Test that numeric multiplication works" do
        m = Multipler.new(3)
        assert_equal(6, m.times(2))
        assert_equal(-9, m.times(-3))
      end

      test :alpha, "Test other uses of the '*' method" do
        m = Multiplier.new("hi")
        assert_equal("hihi", m.times(2))
        assert_equal("",     m.times(0))
      end

      def initialize(by)
        @by = by
      end

      def times(n)
        @by * n
      end

   end

When run with ruby -rtest ..., the test cases get run. When rdoc'd,
the test code gets extracted and used as class-level documentation.

I'm still not sure about this - what do folks think?


Dave