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