Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron

Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-03-17 10:10:30

> -----Original Message-----
> From: boost-users-bounces_at_[hidden] [mailto:boost-users-
> bounces_at_[hidden]] On Behalf Of John Maddock
> Sent: Thursday, March 17, 2011 11:25 AM
> To: boost-users_at_[hidden]
> Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by
FredericBron
> 
> > * I note that is does not use an automated system like Doxygen of
> > producing the reference information.

> > I would like to see the whole library Doxygen fully commented (ask if
> > you think I can help) - replacing much of the current reference text.
> 
> Personally I wouldn't, sorry, but I'm still not completely sold on Doxygen
:-(

Well I agree that it isn't the perfect tool.

(Doxygen gets confused with C++ and it's picky about linking comments to
classes etc).

As a user I find the current 'hand-written' alternatives deeply
unsatisfactory.

The bald synopsis just isn't good enough for the user.

The synopsis just gives the class and function name and parameters types.

But the user also needs to know what the parameters do, what the class or
function does, what preconditions, what post conditions, what side effects,
the "here be dragons" warnings, how to use it, examples ...

Most of this information *has* to be hand-written - whether in plain text,
or in comments of some sort.

And it should all be in one place, not scattered.

Only the Quickbook-Doxygen reference section seems to do this - *provided
the actual code is fully commented*.

So If you are going to suggest or produce a better or even the perfect tool
- fine.

But IMO much Boost current documentation just isn't good enough.
 
> My other 'complaints' ...

> Hehe, working on that now.  In any case this is the "old" type_traits, not
the
> extension under review.

OK fine - as long as you are on the job, I'm sure it will be fine :-)

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]