Paul A. Bristow
Second, I think you have done a *great job* here - looks nice and I could find my way around easily.
Thank you for your support. I think we still have some way to go though, especially with few missing components.
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.
I'd like to get some feedback from the list before I merge this to master (or before it is released).
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.
I have to disagree with you on this point: 1. We deliver C++ libraries. Reference documentation is essential part of that which. One of the long standing criticism of Boost.Test docs was an absence of proper reference docs. Thus I believe these pages are not (only) for library maintainers, even though User's guide cover all the most common interfaces users need in more friendly format. There are number of extension APIs which require understanding of specific classes (for example to implement custom log output formatter) 2. Another long standing complain from several people (including you if I am not mistaken) was that Boost.Test documentation is poorly organized and just too big. Some people (not to point fingers) suggested to just drop documentation for some of the components of Boost.Test, because they are not important (not used) and confuse the users. To improve the organization of documentation for this version I've split the docs into three separate "domains": User's guide, Advanced Usage Scenarios (I am open for better name here) and Reference. Most public interfaces and components are covered in a first one. Some uncommon customization options and advanced components of Boost.Test (interaction testing for example) are going to be covered in a second. Finally some of the components on Boost.Test which are not part of public API, but can be used independently of Boost.Test plus specific API of classes which are used for code level customization are covered in reference section. I would like to see all three sections to be accessible online and not require users to generate one when necessary. 3. Having "castrated" reference along the Users's guide and real reference on a side seem a rather strange setup. 4. Reference pages produced by quickbook/doxygen rule are unacceptably ugly, missing lots of things (for example they are missing all class level sections and [in] designation for function arguments among many other things). They are also uses least useful file based view on a reference. In a summary: if I can help it we will drop the doxygen rule and just generate proper reference pages.
My only immediate criticism is that I think placing the Output in a second box
I agree with you here. I do not like the current output as well. What do you suggest instead? You seem to dislike my toggle idea.
I'll see if I can deal with any of the other wrinkles above later.
You help is very much appreciated. Regards. Gennadiy