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

From: Cromwell Enage (sponage_at_[hidden])
Date: 2005-12-02 18:27:26

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

Okay, I'll put it at the end of the function.

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

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

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

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

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