RE: [boost] Re: Reference documentation

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
Haskell ;-)

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