Boost logo

Boost :

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-30 17:24:42


Kevin S. Van Horn said:
> 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.

I agree with the sentiment, but there's reasons for both approaches. To
me, the ideal solution would be seperate documentation, but a tool that
could parse both the documentation as well as the code to report any
discrepencies.

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

1) Most literate programming tools allow you to override anything parsed
from the code, so if you wanted to hide the const-ref detail you could.

2) Often, this detail *IS* important, as there's a cost to pass by value
and users may want to employ some technique to overcome this (thinking
mostly in terms of generic interfaces where you can use something like
boost::ref to overcome this "problem").

You do raise some valid points, I just don't think they necessarily have
to exclude auto-generated documentation.

-- 
William E. Kempf

Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk