Re: [Boost-users] [boost-users] Multi-State Mazes and Boost.Parameter

From: David Abrahams (dave_at_[hidden])
Date: 2005-12-02 11:52:06

Cromwell Enage <sponage_at_[hidden]> writes:

> --- David Abrahams wrote:
>> I was unable to find any clear and coherent such
>> presentation.  Care to point me at a specific
> example?
>
> Free functions:
> <http://msmazes.sourceforge.net/doc/api/group__core__graph.html#ga3>

Okay, that's confusing.

What I'm seeing there is:

  bool makeRandomPaths  	(   	   	 ...  	 )   	

    This algorithm creates random paths in the input graph, all from the
    specified source vertex, and places them in the output predecessor
    map. The implementation is based on an algorithm by James Gary Propp
    and David Bruce Wilson, located at http://dbwilson.com/ja/ja.ps.gz.ps
    on page 28. (See http://dbwilson.com/ja/ for output formats other than
    Postscript.)

    The output predecessor map may form a forest instead of a tree; the
    implementation returns false in this case. How you deal with the
    result depends on whether you need all the paths (solved by
    while(!%makeRandomPaths(...)){}) or just the path to a particular
    target vertex (see the example below).

  <SNIP GIGANTIC EXAMPLE>

  Note:
      This function requires the use of named arguments <link to
      Boost.Parameter library>. 

  Parameters:
          input_graph_arg 	the input graph.

          source_vertex_arg 	the root vertex of all the random paths.

          shuffler_arg 	    The random number generator used to help
                              choose random predecessors for vertices.

          output_predecessor_map_arg 	the output predecessor map.

          visitor_arg 	a binary predicate functor that checks if an
                          edge fulfills the caller-defined requirements
                          for being part of a random path. Defaults to
                          an instance of
                          msmazes::DefaultRandomPathEdgePredicate.

* Are you saying this function *can't* be called with positional
  arguments?  If not, why not?  Seems to me you have to jump through
  hoops to impose that restriction and I don't see why anyone would.

* The initial function signature shown at the top should list at least
  the parameter names, maybe in italics or something.  The (...) is
  legal C++ with a completely different meaning.

* Linking to the Boost.Parameter library from "named arguments" is
  probably not helpful.  It suggests that the reader ought to wade
  through the docs for an entire library, mostly made up of details
  that no user of your library should be concerned with, rather than
  simply describing the idiom in a few simple words.

* The example interrupts information that should be grouped together,
  and even if you fix that...

* The example is much too long to be helpful.  It should be something
  I can take in at a glance, rather than something realistic (if you
  have to choose).  Occupying 4 lines of comment and vertical
  whitespace to describe why you're #including each file is
  counterproductive.

> Class member function:
> <http://msmazes.sourceforge.net/doc/api/classmsmazes_1_1_parallelepiped_f_s_m_builder.html#a2>

  template<typename RNGEngine, typename DirectionType = unsigned int, typename DirectionChangeType = int, typename CellContainerSelector = boost::vecS, typename PiConstant = sgdk::Pi, typename TangentFunction = sgdk::Tangent>
  void msmazes::ParallelepipedFSMBuilder< RNGEngine, DirectionType, DirectionChangeType, CellContainerSelector, PiConstant, TangentFunction >::initialize 	(  	  	... 	 )  	

Ack!! too wide!  I can't possibly understand that.  Reformatting:

  template<
      typename RNGEngine, 
      typename DirectionType = unsigned int, 
      typename DirectionChangeType = int, 
      typename CellContainerSelector = boost::vecS, 
      typename PiConstant = sgdk::Pi, 
      typename TangentFunction = sgdk::Tangent
  >
  void msmazes::ParallelepipedFSMBuilder< 
     RNGEngine, 
     DirectionType, 
     DirectionChangeType, 
     CellContainerSelector, 
     PiConstant, 
     TangentFunction >::initialize 	(  	  	... 	 )  	

Do you really want to show every member of
msmazes::ParallelepipedFSMBuilder<...whatever...> in out-of-class
member notation, repeating all the default arguments?!

  Initializes this ParallelepipedFSMBuilder.

  Note:
      This function requires the use of named arguments. 

  Parameters:
          maze_maker_arg 	the maze graph builder.
          fsm_input_maker_arg 	the input maker.
          maze_policy_arg 	a maze policy associated with maze_maker_arg; defaults to boost::mpl::void_().
          init_tesselation_selector_arg 	see Parallelepiped.
          init_entrance_cell_arg 	see Parallelepiped.
          init_exit_cell_arg 	see Parallelepiped.
          init_cell_minimum_arg 	see Parallelepiped.
          init_cell_maximum_arg 	see Parallelepiped.
          init_cell_increment_arg 	see Parallelepiped.
          init_zero_direction_arg 	see Parallelepiped.
          init_positive_rotation_arg 	see Parallelepiped.
          init_zero_tolerance_arg 	see Parallelepiped.

The "see Parallelepiped" links don't send me directly to anything I
would call a description of the requirements on or meaning of those
parameters.  Don't make the reader dig, or the docs will be useless.

> Concept which the above class models:
> <http://msmazes.sourceforge.net/doc/api/concept__fsm__builder.html>

I don't see any relevance to the parameter library on that page.

HTH,

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