Re: [boost] [test] still broken in release

Subject: Re: [boost] [test] still broken in release
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-08-15 05:02:08

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Gennadiy Rozental
> Sent: Wednesday, August 14, 2013 10:23 PM
> To: boost_at_[hidden]
> Subject: Re: [boost] [test] still broken in release
> 
> Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:
> > I hope so too.  I find Richard's Quickbook/Doxygen version *much* more
> > user-friendly.
> 
> I do not follow this statement. Why Boost.Test users would care what media is used for writing
docs.
> How using doxygen make it more user-friendly than any other solution?

Because it is familiar - the look'n'feel is similar to lots of other Boost libraries.
They know how to navigate it.
 
> > Putting the function and macro descriptors in the code is popular
> > because it keeps the docs close to the code and makes it more likely
> > that the two are kept in sync.
> >
> > Doxygen simply automates the process of making it accessible from the
> > Quickbook C++ reference section.
> >
> > Of course the quality of the Doxygen comment descriptions is the key
> > to making the docs really work for the user.
> >
> > (Too many people have been put off Doxygen because authors have
> > thought that all they needed to do was to feed the C++ code into
> > Doxygen and the job was done.  This is quite wrong - the real task is
> > still to add comments to document the functions and macros etc).
> 
> I had an extensive expirience with Doxygen recently (had to document massive project at work). It
does
> indeed have it's uses, but:
> 
> 1. It is primarily should be used for *reference* documentation. It is not a good media for user
guide
> kind of pages.

Absolutely - it's only used for that.

The link between Doxygen was done by Doug Gregor years ago and is used on many big Boost projects.

Quickbook also provides a nice way of providing the main descriptive stuff, tutorials ...

And Quickbook's code snippets ensure that the code in docs has actually compiled and run.

> It is fine to have few lines next to the function/class declaration, but once we start writing
long
> complicated usage explanations code become unacceptantly cluttered for developers and unreadable
> for viewers. Take BOOST_TEST for example. It is just line in a header and probably 20 pages in
docs.

Yes - but you can easily provide links to the descriptive text sections and anchors too.

> 2. It does help sometimes to see these comments next to headers, but they also bring false sense
of
> security

Yes - it would be better if the compiler was more tightly coupled to the documentation tool.
 
> 3. Doxygen is not smart enough.

OK, but Doxygen is the best tool that we have, and is still being improved.

It's main weakness is controlling things that we don't want documented, but that could be improved
with the will, and enthusiasm.

>Otherwise all library authors are free to use trunk version of Boost.Test to try new features.

But that's a bit scary ;-)

Paul

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