From: Jamis Buck <jgb3@...>
Date: 2004-10-12T12:10:20+09:00
Subject: Re: documentation as source

Randy W. Sims wrote:
> Are there any Ruby modules that allow documentation to act as source 
> code? I was thinking of the problem of how souce code sometimes diverge 
> from its documentation. So maybe there could be a way to specify the 
> interface: the number of arguments and their types in the documentation, 
> and possibly pre- and post-conditions, and then the documentation would 
> be turned into code at runtime. I guess this would be implemented 
> something like Perl's source filters[1]. Possibly some constants and 
> such could be defined this way as well, version numbers, etc.
> 
> I'm not sure if this is a good idea or not; I haven't completely thought 
> it through. It seems like I've read about this being done before in some 
> other langage, but a brief search hasn't turned up anything.
> 

I haven't seen it done in Ruby, but the general idea is called "literate 
programming". If you google for that term, you'll find lots of information.

I'm not a big supporter of the idea, though I've never done more than 
tinker with it. I'd be curious to see what you come up with if you do 
find a way to do it in Ruby, though.

- Jamis

-- 
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis