Joel de Guzman <joel@boost-consulting.com> 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