[boost] boost::proto documentation for transforms

From: Maurizio Vitale (mav_at_[hidden])
Date: 2007-04-27 01:49:26

I think the documentation for transforms could be improved by giving
apply and call equal importance and emphasizing the fact that apply
computes compile time information (and not necessarily, I think, only
the type of call) while call is a method that can be called at
run-time.

The documentation right now says:

  A meta-grammar decorated with transforms has a static member function named
  `call()` which takes three parameters:

  * `expr`    -- the expression to transform
  * `state`   -- the state of the transformation so far
  * `visitor` -- any optional auxiliary mutable state information

  It also has a nested `apply<>` template which is used to calculate the return
  type of the `call()` member function.

and later:

  The static `call()` member function is needed to complete the transform
  interface. It simply returns a default-constructed object, which will be an
  instantiation of `mpl::int_<>`.

This leads one to believe that both are necessary (otherwise the
interface would be 'incomplete' as hinted by the second sentence) and
that all apply is supposed to do is to compute the return type for
call. Further, the first fragment make one think that call() is the
important thing and apply is just an ancillary metafunction.

The example calc3 was the one that cleared things up for me: there
only apply is defined, but more importantly comments around the
commented out call() method talks about the unneeded 'run-time
counterpart for the transform'.  I think this dichotomy should be made
more clear in the documentation.

An example where the runtime part does more than just reifying the
compiletime side, by generating more complex code might also be usful.

I might have something that computes code for overflow handling and/or
(more complex) quantization handling, if only I could make it work
with proto...
I'm sure there's code that does this in xpression as well, but that
code is probably a bit too complex for beginners.

Regards,

        Maurizio