Cromwell Enage
--- 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...
template
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