Re: [boost] [test] boost.test owner unresponsive to persistent problems for multiple years

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:

Hi Paul,

> 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