Boost logo

Boost :

Subject: Re: [boost] [test] boost.test owner unresponsive to persistent problems for multiple years
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2015-01-09 05:50:14


> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Gennadiy
> Rozental
> Sent: 08 January 2015 17:25
> To: boost_at_[hidden]
> Subject: Re: [boost] [test] boost.test owner unresponsive to persistent
problems for
> multiple years
>
> 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.

> > 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:

OK - well how about providing just the Standalone Doxygen docs, prebuilt in
doc/doxygen,
and accessible view a link from the main docs TOC?
 
> 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.

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

Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk