Blake wrote:

> On Mon, 18 Oct 2004 16:24:51 -0700, Michael Latta <lattam at mac.com> wrote:
> 
>> I favor comments over documentation in some other repository because 
>> it  increases the chance that the next poor sod to work on my code 
>> will be  able to find it.  The word documents prepared at various 
>> points and  placed under CM are never as easy to locate as comments in 
>> the code.
> 
> 
> I think what's excited me about this discussion is that I can see a  
> comment system that could actually work, if it were externally and  
> internally synchronous. Externally, for clients of the system who want 
> to  use the objects without having to go through the code, and 
> internally for  those who want or need to get into them. Also, the 
> notion of an OO comment  system intrigues me, where comments are inherited.

Hi Blake,

You might enjoy studying a documentation feature of Eiffel called 'short 
form'. The Eiffel programming language has a form of executable 
OO-documentation that is inherited.

This OO-documentation is part of the source code but can easily be 
extracted by tools to show only the documentation of each class. A bit 
like JavaDoc, but richer. This extracted form is called 'short form'.

But the really cool part is that you can turn on a compiler switch and 
have the executable documentation checked, at runtime, against the 
actual code and get warned if the code and the executable documentation 
disagree in any way.

It's common for Eiffel developers to run their code with the compiler 
switches set to run most, or all, of the checks. Thus, when they trust 
their 'short form' documentation, they have a good reason to do so.

Cheers,

Peter