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@cc.gatech.edu)