Boost :

From: David Bergman (davidb_at_[hidden])
Date: 2002-10-30 17:51:01

Yes,

What if Boost demands a literal programming style such as the Literal

People would love to (1) have to embed all code in comments or special
blocks (such as \begin{code} in LaTeX and Literate Haskell) and (2) run
the code through a code extractor before compiling and/or publishing the
code to the project repository.

/David

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of William E. Kempf
Sent: Wednesday, October 30, 2002 5:25 PM
To: boost_at_[hidden]
Subject: Re: [boost] Re: Reference documentation

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
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost