-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: 08 January 2015 17:25 To: boost@lists.boost.org Subject: Re: [boost] [test] boost.test owner unresponsive to persistent
problems for
multiple years
Paul A. Bristow
writes: Hi Paul,
Second, I think you have done a *great job* here - looks nice and I could find my way around easily.
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
OK - well how about providing just the Standalone Doxygen docs, prebuilt in doc/doxygen, and accessible view a link from the main docs TOC? 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.
IMO they are wrong - it is not the *size* but the *search and navigation* that were missing/misleading. But for others to comment usefully on Boost.Test new docs , you need to put the *built* docs somewhere (most people don't have tools to build in place). Putting the derived files in /doc/html in GIT is a recipe for trouble (as we have found with Boost.Math) if you have more than one author. But as a *temporary measure* while you get comments this might be good? Dropbox? (but then it looks horrible without access to the .css, icons and logo etc)
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.
OK - If you think that Quickbook/Doxygen C++ reference section is unhelpful, then use the Standalone Doxygen, and just link to it, something like "Boost.Sort C++ Reference section is provided in Doxygen format at" [@/doxygen/index.html] But it is the content of the Doxygen comments and links, especially to examples, that are the key to it being useful to the user (rather than to maintainers).
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'd just put the output is a snippet below. It doesn't matter if it is long and tedious - users will scroll over or hyperlink somewhere else quickly. This seems to work perfectly well in many libraries. Another way is to use callouts (I dislike these, as footnotes, because they force the user to move his eye down to the bottom of a potentially-off-the-page page). For simple one-line outputs, you can add inline comments std::cout << 2 + 2 << std::endl; // Outputs: 4 HTH Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830