Re: [boost] Re: Reference documentation

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