Re: [Boost-users] [Phoenix] Review: Documentation

Subject: Re: [Boost-users] [Phoenix] Review: Documentation
From: Joel de Guzman (joel_at_[hidden])
Date: 2008-09-30 03:38:40

Roland Bock wrote:
> Hi Joel,
> 
> Joel de Guzman wrote:
>>> For example, the actor's page. It says that it is the main concept 
>>> and it shows a template and with one parameter, which does not appear 
>>> anywhere near the template's body. And that's pretty much it. It does 
>>> not say anything about when it is used, by whom, or what the 
>>> necessary characteristics of the template argument "Eval" are. 
>>> Nothing. Except:
>>> "Don't worry about the details, for now."
>>
>> And at that point, it's certainly the case. It's just short of saying
>> that, hey, you need to know about this class, but not in detail.
>> The details will be discussed later.
> 
> Well, maybe then it is even too much to show the template code? I admit, 
> I was staring at it, wondering what it might tell me.

Ehm, no, I don't think so ;) But thinking about it some more,
perhaps I can show the real C++ concept, because that's what
it really is. Ok, I'll formalize that into a C++ concept form.

>> Yes, and that's all you need to know at that point. More detail
>> will be provided in subsequent sections. Providing the details
>> at this point, IMO, would distract from the main subject matter.
> 
> OK, my point is that I fail to see what the main subject matter is on 
> that page. I promise to learn more about FP and instead of saying "This 
> could be better", I will try to come up with contribution to the 
> documentation.

Great!

>> The least I could do, perhaps, is to provide links to other parts
>> in the doc where these are explained in detail, for those who
>> are itching to know more. Is that an acceptable solution?
> 
> Sounds good to me :-)
> 
>> To be honest, it will be hard to find examples that would please
>> everyone, but you have a good point and I'll try to find a
>> sweet set of examples beyond the "First Practical Example".
> 
> Great! Maybe I develop useful examples on my own while learning more 
> about FP. If so, I am going to share them, of course.

Even greater!

> Thanks for your efforts!

Most welcome, Roland.

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://spirit.sf.net