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

From: David Abrahams (dave_at_[hidden])
Date: 2005-12-02 19:23:02

Cromwell Enage <sponage_at_[hidden]> writes:

> --- 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 <whatever.hpp>     // for the whatever component

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

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