Subject: Re: [boost] [test] boost.test owner unresponsive to persistent problems for multiple years
From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2015-01-08 12:24:45
Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:
> 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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk