[boost] Re: Reference documentation

From: Kevin S. Van Horn (Kevin.VanHorn_at_[hidden])
Date: 2002-10-30 16:45:07

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*.  (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.