Re: [boost] [ANN] Phoenix-2 prerelease

From: David Abrahams (dave_at_[hidden])
Date: 2005-11-03 16:38:31

Joel de Guzman <joel_at_[hidden]> writes:

> Comments, feedback very welcome!

> Organization
> 
> Care and attention to detail was given, painstakingly, to the design
> and implementation of Phoenix. The overall design of the library is
> well structured and clean.

Remarks like the last one usually cause me to be more suspicious of,
than confident in, a library design.  I suggest you strike it.

> The library is organized in four layers:
> 
> The modules are completely orthogonal.  

I'm not sure what that means.  If you're going to say it, you should
explain it.

> The relationship between the
> layers is totally acyclic.

  "The modules are orthogonal, with no cyclic dependencies"

http://www.asne.org/index.cfm?ID=4364

> Lower layers do not depend nor know the
> existence of higher layers. 

  "Lower layers do not depend on higher layers."

http://www.asne.org/index.cfm?ID=4364

> Modules in a layer do not depend on
> other modules in the same layer. 

Wonderful!  

> This means for example that the
> client can completely discard Bind if she does not need it; or
                                                            ^
                                           that should be a comma

> perhaps take out Operator and Statement and just use Function, which
  ^^^^^^^^^^^^
  "she can leave"

> is desireable in a pure FP application. 
  ^^
  "would be"
> 
> The library has grown from the original Phoenix but still comprises
> of only header files. There are no object files to link against.
  ^^
strike

> Core
> 
> The lowest two layers comprise the core.
> 
> The Actor is the main concept behind the library. Lazy functions are
> abstracted as actors which are actually polymorphic functors. 

That is one scary sentence.  Can you simplify it?  What are you really
trying to say?

> There are only 2 kinds of actors:
> 
>    1. Primitives
>    2. Composites
> 
> Composites are composed of zero or more actors. Each actor in a
> composite can again be another composite. Primitives are atomic
> units and are not decomposable. 

Again, what does "decomposable" mean?

> Modules
>
> Module 	Description
>
> Function 	Lazy functions support (e.g. add)
>
> Operator 	Lazy operators support (e.g. +)
>
> Statement 	Lazy statments (e.g. if_, while_)
>
> Object 	Lazy casts (e.g. static_cast_), object creation
>           destruction (e.g. new_, delete_)

> Scope 	Support for scopes, local variables and lambda-lambda

"lambda-lambda?"

> Bind 	Lazy functions from simple monomorphic, plain functions,
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
              Can't you say this with 1 or 2 words instead of 4?

>       member functions or member variables for deferred evaluation.
                            ^^^^^^^^^^^^^^^^
                            "data members"

What does "for deferred evaluation" add here?

> Intrinsic 	Set of predefined "lazy" functions that work on STL
                ^^^^^^
                strike
>               containers and sequences (e.g. push_back).

I would call that module "container."  It isn't the intrinsics of the
phoenix library, but of the STL container library.

> Algorithm 	Set of predefined "lazy" versions of the STL
                ^^^^^^
                strike.
>               algorithms (e.g. find_if).

> Includes
> Module 	File
> Core 	#include <boost/spirit/phoenix/core.hpp>
> Function 	#include <boost/spirit/phoenix/function.hpp>
> Operator 	#include <boost/spirit/phoenix/operator.hpp>
> Statement 	#include <boost/spirit/phoenix/statement.hpp>
> Object 	#include <boost/spirit/phoenix/object.hpp>
> Scope 	#include <boost/spirit/phoenix/scope.hpp>
> Bind 	#include <boost/spirit/phoenix/bind.hpp>
> Intrinsic 	#include <boost/spirit/phoenix/intrinsic.hpp>
> Algorithm 	#include <boost/spirit/phoenix/algorithm.hpp>

At this point in the docs you'd do better to write it in English:

  Each module is defined in a header with the same base name. So for
  example, the core module is in <boost/spirit/phoenix/core>.

> Finer grained include files are available per feature. See the
                                                       ^
                                    a semicolon would be good here
> succeeding sections.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com