Paul A. Bristow
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.
Thanks! We are defining the scope of the next release, we definitely want some "must have" features to be properly documented.
Fourth The Standalone Doxygen shows the structure and how it works
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
internally. 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
You have a point. Our current concern is that the documentation is huge and it is hard to find a good way of presenting all the features in boost.test. Parts such as execution monitor are very advanced, and have enough content to have their own section. This thing is that, from a user perspective, it is hard to understand what such parts have to do with boost.test. So we think it is better to have a separate document for these parts. One option is to have these parts documented in doxygen only, with \sections and everything doxygen is able to provide. The other option is to have several quickbook documents (users guide, users reference, advanced topics, full reference), but I do not know if it would address the issue. precious. We use a template, and those changes are straightforward. I was wondering if, with quickbook, it would be possible to have: - either an output that is "folded" by default and "unfolded" dynamically when the user clicks it - or an output created on another page, without creating a section under the current one - and finally if all these can be easily disabled for the PDF output Finally, for the arrangement of the table columns, would some "fluid container" provided by bootstrap address this issue?
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.
[...]
We use code snippet almost everywhere. The example you mention has also its .cpp and has been checked, although not in an automated manner. We reproduced the code in this very example because we wanted the macros expansion. All snippets have the same markup "example_code" (looks like a trick to quickbook) and allows us to use the same template for all snippets/examples. This is also the case for the outputs. I was not able to disable the default rendering for the output also (using [teletype] instead).
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++
Its current parsing is impressive considering the labyrinthineness of C++ language, but imperfect.
One thing I am fairly sure is that the <at> 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
code). things
brackets by DETAILS, or not).
Some of the bug reports suggest that <at> as a trip character may
Ok. What I see is that the \internal pieces appear in the final XML, without any mention of the internal itself. I also noticed that the operator overload is not properly rendered. 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
Thanks for your support. One last question: I just noticed the existence of the develop doc website http://www.boost.org/doc/libs/develop/libs/libraries.htm How often is it updated? Best, Raffi