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

From: shunsuke (pstade.mb_at_[hidden])
Date: 2008-04-06 14:40:13

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.
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.

> 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.

> "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.

> 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