Joel de Guzman <joel <at> boost-consulting.com> writes:
When reviewing a language (yes, FC++ *is* a language, or more particularly, an EDSL--embedded domain specific language; sure Spirit is also an EDSL),
<snip>
* What is your evaluation of the documentation?
In a word: poor. However, I'm sure the author(s) are aware of this and I'm sure we'll see better documentaion in the future.
Examples speak volumes. I'd like to see more fully commented or annotated client applications and examples from the simple to the complex preferably hooked into the documentation.
Tutorials. I'd like to see a tutorial that hand-holds a would be user into the FC++ realm.
I would choose the word 'misdirected'. I just had the pleasure to read the spirit user's guide front-to-back on the weekend, and as a C++ programmer with very little knowledge of the field of parsing, I found it to be very attuned to my learning curve. The documentation in FC++ on the other hand is directed more at programmers who understand the functional programming domain, and now want to apply those concepts in C++. Thus, it didn't really help me identify situations where I would benefit from FC++, and therefore didn't hold my interest through the necesary detail learning phase. (Aside: why is FC++ targetted the way it is? Why are Haskell programmers migrating to C++ anyway? Or is this the wrong conclusion to draw?) I don't think that it's tutorials that are required so much, but motivating examples. I think most C++ programmers come to boost from imperative programming, and it's great to find support in boost for alternative ways of doing things. But documentation for those methods must take the viewpoint that they are introducing alternative methods to C++ programmers in order to be effective. All that aside, misdirected documentation will merely consign FC++ to (relative) obscurity - if the functionality and implementation are of the desired quality, those who already understand the paradigm will derive benefit from its acceptance into boost. Matt