[boost-users] [ANN] Multi-State Mazes for C++ uses Boost
At long last, my multi-state mazes project has come to fruition! It's hosted at http://msmazes.sourceforge.net/ Description: Multi-State Mazes for C++ is a library for game developers that want to incorporate random multi-state mazes into their applications. A primer on the concept of multi-state mazes can be found at http://www.logicmazes.com/; the binary distribution includes a prototype implementation of the walkthrough arrow maze concept. Libraries used: * Boost.Graph * Boost.Random * Boost.Parameter (Please browse the documentation at http://msmazes.sourceforge.net/doc/api/ and comment on how I present the functions that use named arguments.) * Boost.MPL * Boost.DynamicBitset * Boost.uBlas (Particularly the vector and matrix class templates.) Have fun! Cromwell D. Enage __________________________________ Start your day with Yahoo! - Make it your home page! http://www.yahoo.com/r/hs
Cromwell Enage
* Boost.Parameter (Please browse the documentation at http://msmazes.sourceforge.net/doc/api/ and comment on how I present the functions that use named arguments.)
I was unable to find any clear and coherent such presentation. Care to point me at a specific example? One thing did strike me: you seem to be setting BOOST_PARAMETER_MAX_ARITY to different numbers in different header files. That could be a problem in several ways: 1. ODR violations 2. Macro redefinition errors when two of these headers are included in the same TU -- Dave Abrahams Boost Consulting www.boost-consulting.com
--- 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 Class member function: http://msmazes.sourceforge.net/doc/api/classmsmazes_1_1_parallelepiped_f_s_m... Concept which the above class models: http://msmazes.sourceforge.net/doc/api/concept__fsm__builder.html
One thing did strike me: you seem to be setting BOOST_PARAMETER_MAX_ARITY to different numbers in different header files.
Actually, no. You must have been looking at the example programs. (I should have made that clear in the synopsis of each class/function that had an example.) The Core Library itself never defines BOOST_PARAMETER_MAX_ARITY; instead, each header file defines an internal macro that requirest BOOST_PARAMETER_MAX_ARITY to be at least a certain value; this macro is #undef'd at the end of the header file. Cromwell D. Enage __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
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
--- David Abrahams wrote: http://msmazes.sourceforge.net/doc/api/group__core__graph.html#ga3
* 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.
Do you mean mixing positional arguments with named arguments? Or providing an alternate, positional-argument interface to the function? If the former, then I'd prefer to wait for the BGL to integrate Boost.Parameter, then follow their example on this. OTOH, I could easily expose the corresponding implementation function, along with a version that uses all the defaults, and then perhaps tell the users, "Hey, wouldn't your code look much more maintainable if it used the named-argument interface?"
* 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.
I'll have the parameter names link out somewhere, i.e. the documentation for their respective keyword.hpp files (and expound on the documentation for that file). The links in the function signature *should* be sufficient to differentiate the function from regular functions.
* Linking to the Boost.Parameter library from "named arguments" is probably not helpful.
Yeah, you're probably right. I'll flesh out the idiom at the introduction.
* 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
Okay, I'll put it at the end of the function. lines of
comment and vertical whitespace to describe why you're #including each file is counterproductive.
Okay, I'll write a simpler example and mark the #include comments as \internal.
template
void msmazes::ParallelepipedFSMBuilder< RNGEngine, DirectionType, DirectionChangeType, CellContainerSelector, PiConstant, TangentFunction ::initialize ( ... )
Ack!! too wide! I can't possibly understand that.
Yeah, Doxygen with the default settings isn't the best tool for autogenerating documentation. I'd learn QuickBook or RST if I had the time...
Do you really want to show every member of msmazes::ParallelepipedFSMBuilder<...whatever...> in out-of-class member notation, repeating all the default arguments?!
The "see Parallelepiped" links don't send me directly to anything I would call a description of
Tell me how to turn off all those template arguments in Doxygen and I will. Otherwise, I could make a local copy of the header files whose sole purpose would be to facilitate document autogeneration. We'll see how that works out. the
requirements on or meaning of those parameters. Don't make the reader dig, or the docs will be useless.
So I'll copy and paste, then.
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.
The only relevance is that a Finite State Machine Builder requires initialization, and that the initialization parameters are specific to each model, which *may* or may not employ named arguments. Cromwell D. Enage __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
Cromwell Enage
--- David Abrahams wrote: http://msmazes.sourceforge.net/doc/api/group__core__graph.html#ga3
* 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.
Do you mean mixing positional arguments with named arguments? Or providing an alternate, positional-argument interface to the function?
?? The normal usage of the parameter library results in a positional interface that can also accept named parameters. Did you do something abnormal to disable the positional interface?
If the former, then I'd prefer to wait for the BGL to integrate Boost.Parameter, then follow their example on this.
OTOH, I could easily expose the corresponding implementation function, along with a version that uses all the defaults, and then perhaps tell the users, "Hey, wouldn't your code look much more maintainable if it used the named-argument interface?"
I don't understand why you'd complicate things that way.
* 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.
I'll have the parameter names link out somewhere, i.e.
I can parse that, but can't attach semantics.
the documentation for their respective keyword.hpp files (and expound on the documentation for that file). The links in the function signature *should* be sufficient to differentiate the function from regular functions.
Well, you got my feedback; take it or leave it. I'm not 100% positive I'm understanding you, but it looks like you're leaving it.
* 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.
Okay, I'll write a simpler example and mark the #include comments as \internal.
Or use endline comments if you need to:
#include
template
void msmazes::ParallelepipedFSMBuilder< RNGEngine, DirectionType, DirectionChangeType, CellContainerSelector, PiConstant, TangentFunction ::initialize ( ... )
Ack!! too wide! I can't possibly understand that.
Yeah, Doxygen with the default settings isn't the best tool for autogenerating documentation. I'd learn QuickBook or RST if I had the time...
Doxygen and (QuickBook/RST) are in completely different categories. It's not (or shouldn't be) a choice of one or the other.
Do you really want to show every member of msmazes::ParallelepipedFSMBuilder<...whatever...> in out-of-class member notation, repeating all the default arguments?!
Tell me how to turn off all those template arguments in Doxygen and I will.
Don't use Doxygen if that's the best you can do with it. I don't know the first thing about Doxygen; I don't think the onus should be on me to explain how it can be used effectively.
Otherwise, I could make a local copy of the header files whose sole purpose would be to facilitate document autogeneration. We'll see how that works out.
It's your funeral :)
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.
So I'll copy and paste, then.
Ditto :)
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.
The only relevance is that a Finite State Machine Builder requires initialization, and that the initialization parameters are specific to each model, which *may* or may not employ named arguments.
That's a pretty distant connection. Your readers shouldn't have to follow logical routes like that one. -- Dave Abrahams Boost Consulting www.boost-consulting.com
--- David Abrahams wrote:
?? The normal usage of the parameter library results in a positional interface that can also accept named parameters. Did you do something abnormal to disable the positional interface?
Ah, I see what you mean now. No, I didn't do anything; the positional interface is still there, undocumented. I'll let you all know when a revised version is available. Cromwell D. Enage __________________________________ Start your day with Yahoo! - Make it your home page! http://www.yahoo.com/r/hs
--- Cromwell Enage wrote:
Ah, I see what you mean now. No, I didn't do anything; the positional interface is still there, undocumented. I'll let you all know when a revised version is available.
The introductory page http://msmazes.sourceforge.net/doc/api/ has been beefed up to clarify the project's objectives; includes a short, dissected example program. Positional parameters are now documented; again, see http://msmazes.sourceforge.net/doc/api/group__core__graph.html#ga3 for an example. Class template documentation has also been improved; again, see http://msmazes.sourceforge.net/doc/api/classmsmazes_1_1_parallelepiped_f_s_m.... A succinct tutorial on using named parameters is available at http://msmazes.sourceforge.net/doc/api/tutorials__boost.html. Let me know what needs further improvement, and also whether or not I'm going on the right track! Cromwell D. Enage __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
Cromwell Enage
--- Cromwell Enage wrote:
Ah, I see what you mean now. No, I didn't do anything; the positional interface is still there, undocumented. I'll let you all know when a revised version is available.
The introductory page http://msmazes.sourceforge.net/doc/api/ has been beefed up to clarify the project's objectives; includes a short, dissected example program.
Positional parameters are now documented; again, see http://msmazes.sourceforge.net/doc/api/group__core__graph.html#ga3 for an example.
Is there a reason all the names end in "_arg?" Seems clumsy.
Class template documentation has also been improved; again, see http://msmazes.sourceforge.net/doc/api/classmsmazes_1_1_parallelepiped_f_s_m....
A succinct tutorial on using named parameters is available at http://msmazes.sourceforge.net/doc/api/tutorials__boost.html.
Nice! However, (The one restriction is that you must put all your positional arguments before your named ones, so use this particular feature with care.) is false. It doesn't make much sense to do otherwise, but it will work. -- Dave Abrahams Boost Consulting www.boost-consulting.com
--- David Abrahams wrote:
Is there a reason all the names end in "_arg?" Seems clumsy.
It's just a convention I use. Of course, after the recent makeover, I lost the rationale behind it, so I'll do away with the suffix for the next release.
A succinct tutorial on using named parameters is available at
http://msmazes.sourceforge.net/doc/api/tutorials__boost.html.
Nice!
However,
(The one restriction is that you must put all your
arguments before your named ones, so use this
Thanks. positional particular
feature with care.)
is false. It doesn't make much sense to do otherwise, but it will work.
Okay. I'll just say, "Use this particular feature with care." Cromwell D. Enage __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
Cromwell Enage
However,
(The one restriction is that you must put all your positional arguments before your named ones, so use this particular feature with care.)
is false. It doesn't make much sense to do otherwise, but it will work.
Okay. I'll just say, "Use this particular feature with care."
I don't see why that would be any more dangerous than using only positional arguments. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Cromwell Enage writes:
David Abrahams wrote:
However,
(The one restriction is that you must put all your positional arguments before your named ones, so use this particular feature with care.)
is false. It doesn't make much sense to do otherwise, but it will work.
Okay. I'll just say, "Use this particular feature with care."
I don't see why that would be any more dangerous
--- David Abrahams wrote: than using
only positional arguments.
Hmmm. What should I tell the user about these features? Should I present a small "Best Practices" outline, or will a general "Pros & Cons" table work better? Or is it best to say nothing in this case? Cromwell D. Enage __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
participants (2)
-
Cromwell Enage -
David Abrahams