Dave Thomas wrote:

> On Nov 25, 2004, at 15:32, benny wrote:
>> Now the idea: Why not use the examples in the unit-tests (at least the
>> "positive ones") as link to a popup window "examples" in the
>> HTML-documentation created by rdoc?
> 
> I've been thinking a bit about this. I'm nervous about imposing my own 
> rules on how tests are organized and how methods are named: I'd like 
> RDoc to be as transparent as possible.

Well, it would just be a style suggestion. There's no reason to enforce 
tests being inlined into the documentation of methods, but there are use 
cases where it makes good sense to do so. (Specification by example 
comes to mind.) I'm not sure I understand the point about method names.

> So here's another take on it.  You can already link from the method to 
> its test using standard RDoc hyperlinks. How about adding a slight bit 
> of new linking smarts: if you hyperlink to a class/method where the 
> class name starts Test and the method name starts test_, RDoc will 
> hyperlink to it in a different window. That way you can read the 
> mainline code, and scroll to the appropriate test in the test window by 
> clicking. You comment block might contain:
> 
>    # burble burble burble. Burble burble burble. Burble burble burble
>    # burble burble. See the unit test in TestThingie#test_create

I think this is too indirect. I'd really like to see the sample code 
inlined in the documentation, but formatted differently so it stands 
out. Being able to toggle the visibility of sample setup code would also 
be a nice thing, but it isn't as important to me. Of course this is just 
my personal opinion and other's are likely to have other thoughts about 
this.