Boost logo

Boost :

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"

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

  "Lower layers do not depend on higher layers."

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


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

> 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


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

Boost list run by bdawes at, gregod at, cpdaniel at, john at