Boost logo

Boost :

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.

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