Re: [boost] Re: Reference documentation

From: Greg Colvin (Gregory.Colvin_at_[hidden])
Date: 2002-10-30 16:56:57

At 01:45 PM 10/30/2002, you wrote:
>There has been some talk about wanting to extract documentation from  
>source code.  I'm not sure that this is a good idea.  After all, we want  
>to document a *specification*, not an *implementation*. 

I share this concern.

> (If you're 
>writing an implementation guide, feel free to ignore everything that 
>follows.)  Ideally, one should write the documentation *first*, then 
>implement.  Yes, I know that, especially with generic libraries, an 
>iterative process of document and code is often unavoidable.  Still, I 
>have my concerns about encouraging "after-the-fact" specifications, and 
>about the possibility of implementation details leaking into the 
>documentation when the latter is automatically generated from source code.
>
>In at least one case, automatically-generated documentation can't avoid  
>revealing implementation details that should, perhaps, be hidden from the  
>user.  For example, suppose a define a function f that takes arguments of  
>type foo_t.  Does it matter to the user whether the signature of f is 
>"void f(foo_t)" or "void f(foo_t const &)"?  As the implementor of f, I  
>might like to have the freedom to switch between the two signatures  
>depending on whether or not I need a copy of the argument.
>
>
>_______________________________________________
>Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost