Re: [boost] Re: Re: Re: FC++ Formal review half way over today (ends 2/23)

From: Brian McNamara (lorgon_at_[hidden])
Date: 2004-02-26 16:28:43

On Thu, Feb 26, 2004 at 05:43:13PM -0300, Fernando Cacciola wrote:
> Have you seen my "formal" review from couple of days before? (there's the
> vote in there)
> I'd like to know your thoughts about the documentation issues I mentioned.

Ok.

> 1) The documentation that comes with the boost version is not self
> contained. It refers to external documents (on the FC++), which AFAICT are
> required reading in order to know and understand all of the library.
> Most boost users would expect to get everthing they need in the download and
> they will be discouraged if they find out they need to pick additional
> documentation elsewhere.

Point taken, though I think the only "required reading" on the FC++ web
site is the stuff on monads (which is one part of the library I am
convinced does not yet deserve to be in Boost) and a couple of
optimization things (involving odd_lists and reusers; these should be
added to the Boost documentation, but you don't need to know about them
to use the library).  (Do you disagree?)

> 2) There are too many features which are underdocumented or not documented
> at all: they're just shown by example or merely mentioned. Examples are
> strict_list, the epilog functions, most of the special lambda stuff
> (let/letrec,LETtype....)

This I agree with.
The strict_list example and the lambda stuff will be easy for me to
remedy, I think (the interfaces are simple).
Failing to document the Haskell prelude was an error on my part of the
type you describe below.

> In general, the documentation shows FC++ as a FP library "for functional
> programmers who want to do some C++"
> Most of the stuff ommited or barely mentioned are well know to FP
> programmers, but to most C++ programmers they are very obscure (LISP-derived
> languages keep on using short meaningless identifiers, and so does FC++)
> 
> It might be ok for FC++ itself to be targeted to FP programmers (after all,
> it is a functional programming library), but IMO Boost.FC++ should we
> presented the other way around: for C++ programmers who "don't know"
> functional programming "at all", but who are now given the oportunity the
> learn about it, as they apply the concepts and tools to everyday C++
> programming, because of FC++.
> 
> If the documentation of FC++ is reworked with that goal in mind, given the
> reach of Boost, I guess a great deal of the C++ community will get to know
> the best of FP while keeping their (our) favorite language.

I agree.  How sad--when I wrote the Boost documentation, I actually tried 
to make it "C++ audience oriented".  While I think the Boost FC++ docs
are an improvement over the stuff on the FC++ web site, I still
apparently have a ways to go to describe the library in a "C++ friendly"
way.

> And BTW, I'm working through the examples right now...- kind of difficult
> though since I found too many things undocummented.

Indeed; keep in mind that
   The examples in the clients directory are a mix of both
   (regression-type) tests cases which cover the features of the library
   and example applications which demonstrate some of the library's
   utility.  The README file in the client directory gives a short
   explanation of some of the more interesting clients.
It was a mistake on my part to not make any clear delineation between
"examples" and "tests".

If you have questions, feel free to ask (me directly, or on the list);
this won't address the documentation issue, but may at least help you
understand some stuff better now.

Thanks much for your extensive comments, and thanks again for your
"formal" review message.

-- 
-Brian McNamara (lorgon_at_[hidden])