Re: [boost] Egg 2nd request for reviews: Some comments

From: vicente.botet (vicente.botet_at_[hidden])
Date: 2008-04-06 16:51:53

Hi,

thanks for your QUICK answer :-)

----- Original Message ----- 
From: "shunsuke" <pstade.mb_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Sunday, April 06, 2008 8:40 PM
Subject: Re: [boost] Egg 2nd request for reviews: Some comments

> vicente.botet wrote:
>> Hello,
>>
>> As you can see this is not a review. I have no doubt that Egg is an 
>> excelent
>> candidate for a Boost library and that there are a lot of hidden diamons.
>
> Thanks.
>
>> I have only started to read the docummentation (the introduction adn the
>> quick start) and for the moment I'm not sure that I will find the time to
>> see the impementaion. The subject is really abstract and it is hard to 
>> read
>> without stoping every two lines to se if I have realy understood. I 
>> supose
>> that there are other boosters in the same situation.
>
> It is mainly because of my broken english.

Your english is very good.

> I'm still updating Egg document in local everyday to make it better.
>
>> I have a little problem that could be a major one. In the documentation 
>> it
>> is cleary state:
>> "Also, assume that every expression is placed after:
>> namespace egg = boost::egg;
>> using namespace egg;"
>>
>> Does it means that every not prefixed symbol comes from egg? I think that 
>> it
>> will be better to prefix every specific egg class by egg::. There are 
>> some
>> moments that I dont't know if the used class is a egg class or a boost
>> class. This is surely due to the fact that Egg use class or functions 
>> names
>> already  in use on Boost or the STL.
>> This has nothing to be with the contents. I recognize that this is not
>> natural (I'm writing now a library and I use the same style) for the 
>> writer
>> to prefix every new symbol, but I'm sure the reader will apreciate. We
>> shouldn't mix documentation and coding styles.
>
> I will add `egg::` everywhere.
> The same thing was requested in Proto review, IIRC.

Greate, I'm sure that this will clarify the documentation.

>> I dont find too much clear the naming of Major and Little.
>
> Those come from Baseball:
>   Little league(where children play) and Major league(where professionals 
> play).
> I will add this explanation.

I need to continue reading the documentation.

>> "Function Adaptors which take Polymorphic Function Objects then return
>> adapted ones."
>> Could you ad to what these are adapted?
>>
>> "Function Objects which are ports of famous function templates."
>> Could you explain why this is useful?
>>
>> I really think that the introduction do not show clearly what is the 
>> problem
>> Egg try to solve.
>> " Unfortunately, if you need a Polymorphic Function Object whose return 
>> type
>> depends on its argument types, it is not easy. "
>> I think that you should present here what can or can not be done without
>> Egg, and show how Egg helps to do that.
>> The section "Problems of function templates" for the "Quick Start" shoud
>> appear in the introduction to my taste.
>
> I'm inclined to unify "Introduction" and "Quick Start" with more clarified 
> sentences.
>
>> May be you can add a 6th problem: a template cannot be passed to
>> boost::lambda::bind as it seam from the introductuion this is a majot 
>> goal
>> of the Egg library. maybe it would be a good idea to show hwhat the user
>> needs to do today to pass a template to the boost::lambda::bind function 
>> and
>> how Egg make it easier.
>
> I will add "FAQ" which has been asked many times by users in 
> mailing-lists.

I think that you can add this kind of issues on a tutorial.

>
>> One minor remark on the documentation. There is an incoherence on the two
>> first pages:
>> Portability
>> Egg is known to work on the following platforms:
>>
>>   a.. Microsoft Visual C++ .NET Version 7.1 SP1
>>   b.. Microsoft Visual C++ 2005 Express Edition SP1
>>   c.. Microsoft Visual C++ 2008 Express Edition
>>   d.. MinGW with GCC 3.4.4
>>   e.. MinGW with GCC 4.1.2
>>
>> Portability
>> Egg is known to work on the following platforms:
>>
>>   a.. Microsoft Visual C++ Version 7.1 or later
>>   b.. GCC 3.4.4 or later
>
> I wanted to make "Quick Start" quick. :-)
> But it is really an incoherence. It should be fixed.
>
>> The Rationale in the Introduction seam to not add nothing interesting. 
>> Are
>> there some missing links?
>
> No. Maybe I should move it to a more elaborate section.
>
>> I expect to have enough time to do a review, even a little one.
>
> I hope so. Thanks!
>
>
> Regards,
>
> -- 
> Shunsuke Sogame
>

Best
_____________________
Vicente Juan Botet Escriba