From: patrick-may@... (Patrick May)
Date: 2002-06-08T05:16:38+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

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 :-)

good day,

~ Patrick