Boost logo

Boost :

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:

Boost list run by bdawes at, gregod at, cpdaniel at, john at