-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Raffi Enficiaud Sent: 04 January 2015 01:06 To: boost@lists.boost.org 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 +44 (0) 1539 561830