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