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

Subject: Re: [boost] [test] still broken in release
From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2013-08-14 17:23:26

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

It is fine to have few lines next to the function/class declaration, but 
once we start writing long complicated usage explanations code bacome 
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.

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

All too frequently I see incorrect doxygen statements next to modified code. 
Unfortunately compiler does not validate correctnesss of doc 
statements during compilation, so it requires strict discipline from 
developer to maintain these in correct state. Having docs in standalone 
form is not much better, but at least this have a distict indication that 
something else needs to be changed once code is modified. In any case 
this is minot point.

3. Doxygen is not smart enough. 

I spent lot of time telling it what to ignore. There are number of bugs and 
shortcomings in what it supports in modern C++. We can probably work 
around these.

Overall I am fine with using doxygen comments in code, if it is not the only 
form of documentation and they are only responcible for reference 
docs. User guide with all the examples, build rules, detailed semantic 
explanations does not belong to the code. One other thing I hope we can 
keep is dynamic features of current user guide (like hidable example 
outputs)

> Would it help to create a 'Son of Boost.Test' so that each library author
> can try out the new version without fear (and switch back if it doesn't
> work for them).

Not sure about the name ;)... Otherwise all library authors are free to use 
trunk version of Boost.Test to try new features.

Regards,
Gennadiy