From: "Randy W. Sims" <ml-ruby@...>
Date: 2004-10-19T07:47:49+09:00
Subject: Re: documentation as source

Florian Gross wrote:
> Bil Kleb wrote:
> 
>> Randy W. Sims wrote:
>>
>>> Are there any Ruby modules that allow documentation to act as source 
>>> code? 
>>
>>
>> require 'test/unit'
>>
>> Then code test-first and you'll have executable documentation.
> 
> 
> I've coded up test-extract which lets you embed some of your test-cases 
> cloaked as sample code into your RDoc strings.
> 
> It looks like this in practice:
> 
>>     # Creates a Regexp which matches a literal string. In this
>>     # string any special regular expression meta-characters will
>>     # be escaped automatically.
>>     #
>>     #   # This creates a Regexp which will match 3 "foo"s.
>>     #   re = Regexp::English.literal("foo" * 3)
>>     #   re.match("foofoofoo")[0] # => "foofoofoo"
>>     def literal(text); Node::Literal.new(text); end
> 
> 
> (Sample from Regexp::English)

I very much like the idea of being able to test examples embedded in the 
source file's documentation. A couple of suggestions:

1. Is there some way to allow set-up code that is not part of the 
viewable documentation? This would make for clearer examples. Eg. the 
above might be changed to something like:

   #--
   # Init:
   #   foo = Foo.new(blah, blah);
   #++
   #
   # An example of using Foo.bar()
   #
   #   foo.bar(blek)

   def bar(); ...

Well, that's not real pretty, but... the idea is that the example is 
more focused for documentation purposes, and all the setup-code is 
hidden away.

2. In addition to showing how something works, it is sometimes 
instructive to show what doesn't work. Being able to create examples 
that are expected to fail would be useful.

Randy.