Re: [boost] [test] boost.test owner unresponsive to persistent problems for multiple years

Subject: Re: [boost] [test] boost.test owner unresponsive to persistent problems for multiple years
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2015-01-05 12:59:59

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Raffi
Enficiaud
> Sent: 04 January 2015 01:06
> To: boost_at_[hidden]
> Subject: Re: [boost] [test] boost.test owner unresponsive to persistent
problems for
> multiple years
> 
> Gennadiy Rozental <rogeeff <at> gmail.com> writes:
> 
> >
> > Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:
> >
> > > Also are you confident that the various parameters in the doxyfile
> > > the same as passed to Quickbook tools chain?
> >
> > Raffi, can you comment on this?
> >
> Hi,
> 
> My name is Raffi and I am working on boost.test with Gennadiy.
> 
> I enabled the options that show everything but the private and @internal
> documentation.
> What I do is that I look at the intermediate XML generated by the doxygen bjam
> target. If the documented entities are there, I suppose that the doxygen
> configuration is correct.
> 
> Some of the problems we encountered:
> - @overload works for free functions but generates warnings in quickbook for
> member functions
> - grouping of member function using @name completly hides those in quickbook
(no
> warning)
> - @section not shown
> - @param is sometimes not shown in the generated Quickbook

First, I can confirm that I can build the Quickbook docs and the standalone
Doxygen docs.

Second, I think you have done a *great job* here - looks nice and I could find
my way around easily.

Third This should definitely go into master ready for the next release.  Even
with some wrinkles noted above, it will help users a great deal.

Fourth  The Standalone Doxygen shows the structure and how it works internally.
It makes the code maintainable at last, but should not be necessary for the
users.  So just providing the doxyfile in the /doc folder seems fine to me.
Anyone wanting to do maintenance (or ferret in the innards) can build it easily
using the Doxywizard.  (For Windows users, I favour renaming it to a unique
name and file type, say test_doxyfile.txt). This makes up for any limitations in
the Quickbook C++ Reference section.

My only immediate criticism is that I think placing the Output in a second box
to the right of the Code makes assumptions about page width that are probably
unjustified, especially on tablets and phones (which are often used as a second
screen to display manuals etc).

The output box is certain to overflow many screens and will definitely mess up a
PDF version making it useless. I can see that it makes sure that the output is
close to the source, but vertical space is unlimited, whereas width is precious.

I have yet to understand if/how you are using Quickbook code snippets - all the
examples seem to have the same name "example_code" ? 

And this example at least doesn't use a code snippet.

``
#define __BOOST_TEST_MODULE__ My Test
#include <boost/test/included/unit_test.hpp>

__BOOST_AUTO_TEST_CASE__(first_test)
{
  __BOOST_TEST__(true);
  
  int i = 1;
  __BOOST_TEST__(i == 2);
}
``

Code snippets are valuable because the ensure that the code in the docs is the
code in the example and actually runs.  Similarly the output can make ensuring
this much easier.

As to the problems above, I have yet to find time to study in detail, but
getting free of warnings may not be practical (at least until Doxygen is
modified to use the Clang compiler, when it will *really* understand C++ code).
Its current parsing is impressive considering the labyrinthineness of C++
language, but imperfect. 

One thing I am fairly sure is that the @internal command was not found to work
right by Steven Watanabe (our expert on Quickbook internals whose has fixed some
previous bugs, but currently busy on other things).  I have, at his suggestion,
used the \cond ... \endcond command instead to remove implementation details
from Doxygen's sight.  So this is method to use for this (and using a name
\cond DETAILS  ... ) allows the maintainer to show everything, including things
brackets by DETAILS, or not).

Some of the bug reports suggest that @ as a trip character may produce different
(wrong?) results compared to backslash \ as trip.  This may be 'cured' now.
I've built with the hot-off-the-press bug-fix release 1.8.9.1.

I'll see if I can deal with any of the other wrinkles above later.

HTH

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]