Tim Blechmann writes:

hi,

...

...

i've reported an issue before that boost.test in the release branch is pretty broken. *all* tests of the boost.heap testsuite segfault like

this:

...

There were no changes in boost release for several years. Can you wor

karound

...

it for now?

are you sure? this would imply that the boost.heap testsuite was always broken on release, though i'm pretty sure that wasn't the case.

I did not make any chnages. You can check a release branch. Unless something changes in a test setup (new compiler/platform/compilation options). Gennadiy

Richard writes:

[Please do not mail me a copy of your followup]

boost <at> lists.boost.org spake the secret code thusly:

...

I lost my work on new docs unfortunately to broken laptop, still trying to revive it, but I'm lacking time to really get to it.

I wouldn't bother reviving your work on new docs since I am completely rewriting them and am almost finished.

Do you follow trunk or release state of Boost.Test? Gennadiy

Richard writes:

[Please do not mail me a copy of your followup]

boost <at> lists.boost.org spake the secret code thusly:

...

...

boost <at> lists.boost.org spake the secret code thusly:

...

I lost my work on new docs unfortunately to broken laptop, still

trying to

...

...

...

revive it, but I'm lacking time to really get to it.

I wouldn't bother reviving your work on new docs since I am completely rewriting them and am almost finished.

Do you follow trunk or release state of Boost.Test?

I've been working based on trunk, but could easily adapt to another branch if that is the preferred place.

Trunk is the correct place for latest state of Boost.Test.

I posted a call for reviewers on May 1 and am on snapshot 6 right now.

Can I see it somewhere?

- Everything is written in Quickbook - It is a true rewrite, not an edit of existing docs

So you do not see aplace for any of an existing pages in your new documentation? What about examples and existing tutorials? Do you cover all the components of Boost.Test?

- Some Quickbook annotations are added to header files to briefly summarize the major classes/functions that a user of Boost.Test is likely to care about: test_unit, test_case, test_suite, master_test_suite_t, test_observer, unit_test_log_t, unit_test_log_formatter, init_unit_test_func, unit_test_main.

Why does this need to be part of source code?

- Boost.Test code in trunk is used as "the truth" for understanding how something actually works

So, you reverse engeneer all new features, right? Decorators, data based testing, New testing tools (what about old tools?), test unit filtering? Would you be interested in my input? We can take this offline. Gennadiy

Richard writes:

This situation hadn't changed at all in 4 years, so I just decided to fix it by writing new documentation.

Trunk version of docs did improve on that in my opinion, but this is besides the point.

...

...

- Some Quickbook annotations are added to header files to briefly Why does this need to be part of source code?

This is how quickbook keeps documentation and header files synchronized.

So quickbook is like doxigen? Does it parse C++ sources?

...

...

- Boost.Test code in trunk is used as "the truth" for understanding how something actually works

So, you reverse engeneer all new features, right?

It's not clear what is a new feature and what is simply an undocumented internal mechanism. So no, I documented the stuff that everyone needs and the stuff that people appear to be using in boost by grepping trunk. This is already a little bit more than what the old documentation covered.

What is that you cover that existing pages do not, for example? Did you base your decision on what is needed on content of Boost own unit tests? The problem with this is that these obviosly does not include any of new features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these tools are now deprecated and I wouldn't spend any time detailing their use. New testing tools is the one to use from now on and these are the one that needs to be coverred.

...

Would you be interested in my input? We can take this offline.

I will post for wider review once I finish my first pass, which is probably going to happen soon. Right now, I'm just using a few people for feedback as I go.

You are free to do what you think best, but I would imagine that if you want something which reflects real state of Boost.Test (in other words something, which we can actually use for release), we probably need to talk sooner rather than later. Regards, Gennadiy

Richard writes:

[Please do not mail me a copy of your followup]

boost <at> lists.boost.org spake the secret code thusly:

...

The problem with this is that these obviosly does not include any of new features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these tools are now deprecated and I wouldn't spend any time detailing their use.

So you're going to break all the tests that have been written so far?

I don't understand why this is desirable.

We are not going to break anything. These tools are still there, but they are deprecated in favour of new interface. New documentation should cover new interface and can probably refer to last release for old tools. Gennadiy

...

features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these

BOOST_CHECK_EQUAL has been deprecated? What should be used instead?

Very good question, when did this happen, where are the docs for the new version? Thanks, John.

Bjorn Reese writes:

On 08/09/2013 09:01 PM, Gennadiy Rozental wrote:

...

features and these are indeed completely missing from docs. Even worse

...

use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all

they these

BOOST_CHECK_EQUAL has been deprecated? What should be used instead?

BOOST_TEST( a == b ) This will produce as good an output. You can also do BOOST_TEST( a > b ) BOOST_TEST( a != b ) BOOST_TEST( a + b < 2 ) All these will produce detailed output including values of a and b in case if assertion fails. a and b could be collections, in which case above will do per element comparison. a and b could be floating point numbers in which case above will perform comparison with predefined tolerate (predefined for the series of assertions of for the whole test case, and we will also have an ability to specify it as second argument in above assertion). All of this and much much more is the function of new "super testing tool" BOOST_TEST. There are few rare examples where above will not work, BOOST_CHECK will be used instead. You can see more examples in Boost.Test unit tests. Gennadiy

Bjorn Reese writes:

On 08/10/2013 07:11 PM, Gennadiy

Rozental wrote:

Assuming that my foo() function fails,

how difficult is it going to be

to single-step into it (without setting breakpoints inside foo) from a BOOST_TEST(foo()) line? This is a very common scenario for me.

New boost.test has support for this through two macros: BOOST_TEST_UNDER_DEBUGGER If you define this test module will compile in debugger friendly mode. BOOST_TEST_DEBUGABLE If you define this macro test module will perform assertions as usual if you run the test regularly and it will run in debugger friendly mode of you run under debugger (this only available on platforms where we can detect presence of debugger). The price you pay its extra compile time. Gennadiy

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code thusly:

Bjorn Reese writes:

...

On 08/09/2013 09:01 PM, Gennadiy Rozental wrote:

...

features and these are indeed completely missing from docs. Even worse

...

...

use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all

they these

...

BOOST_CHECK_EQUAL has been deprecated? What should be used instead?

BOOST_TEST( a == b )

This will produce as good an output. You can also do

BOOST_TEST( a > b ) BOOST_TEST( a != b ) BOOST_TEST( a + b < 2 )

So what "level" is this? - warning (emit message, test case continues and is not marked failed) - check (emit message, test case contines and is marked failed) - require (emit message, test case does not contiue and is marked failed) -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: Tuesday, August 13, 2013 4:17 AM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release

Richard writes:

...

...

BOOST_TEST( a > b ) BOOST_TEST( a != b ) BOOST_TEST( a + b < 2 )

So what "level" is this?

This is check level, we'll also have BOOST_TEST_WARN, BOOST_TEST_CHECK(same as BOOST_TEST) and BOOST_TEST_REQUIRE.

So, what the resolution? Are you interested to cover latest state of Boost.Test or do I need to

push

forward by myself? Do not take this wrong way - I would definitely prefer to work with someone who is more comfortable with writing docs than doing it all by myself. And I can even live with quickbook, if it can handle all we need. Yet I need to cover new Boost.Test, not rewrite docs for old one. I really hope we can collaborate on this.

I hope so too. I find Richard's Quickbook/Doxygen version *much* more user-friendly. Putting the function and macro descriptors in the code is popular because it keeps the docs close to the code and makes it more likely that the two are kept in sync. Doxygen simply automates the process of making it accessible from the Quickbook C++ reference section. Of course the quality of the Doxygen comment descriptions is the key to making the docs really work for the user. (Too many people have been put off Doxygen because authors have thought that all they needed to do was to feed the C++ code into Doxygen and the job was done. This is quite wrong - the real task is still to add comments to document the functions and macros etc). I hope too that we can get the new Boost.Test fully accepted and working for all Boost libraries. But I understand how difficult it is to make changes when every other library depends on Boost.Test (or should do). Would it help to create a 'Son of Boost.Test' so that each library author can try out the new version without fear (and switch back if it doesn't work for them). Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas Sent: Wednesday, August 14, 2013 8:23 PM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release

...

I hope so too. I find Richard's Quickbook/Doxygen version *much* more user- friendly.

Is this the same as the doxygen_xml2qbk tool in Boost.Geometry?

No - it is the original Doug Gregor et al "C++ reference section" system, as used by several Boost libraries docs. As I've said before, the vital detail is the quality of Doxygen comments in the code. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: Wednesday, August 14, 2013 10:23 PM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release

Paul A. Bristow writes:

...

I hope so too. I find Richard's Quickbook/Doxygen version *much* more user-friendly.

I do not follow this statement. Why Boost.Test users would care what media is used for writing docs. How using doxygen make it more user-friendly than any other solution?

Because it is familiar - the look'n'feel is similar to lots of other Boost libraries. They know how to navigate it.

...

Putting the function and macro descriptors in the code is popular because it keeps the docs close to the code and makes it more likely that the two are kept in sync.

Doxygen simply automates the process of making it accessible from the Quickbook C++ reference section.

Of course the quality of the Doxygen comment descriptions is the key to making the docs really work for the user.

(Too many people have been put off Doxygen because authors have thought that all they needed to do was to feed the C++ code into Doxygen and the job was done. This is quite wrong - the real task is still to add comments to document the functions and macros etc).

I had an extensive expirience with Doxygen recently (had to document massive project at work). It does indeed have it's uses, but:

1. It is primarily should be used for *reference* documentation. It is not a good media for user guide kind of pages.

Absolutely - it's only used for that. The link between Doxygen was done by Doug Gregor years ago and is used on many big Boost projects. Quickbook also provides a nice way of providing the main descriptive stuff, tutorials ... And Quickbook's code snippets ensure that the code in docs has actually compiled and run.

It is fine to have few lines next to the function/class declaration, but once we start writing long complicated usage explanations code become unacceptantly cluttered for developers and unreadable for viewers. Take BOOST_TEST for example. It is just line in a header and probably 20 pages in docs.

Yes - but you can easily provide links to the descriptive text sections and anchors too.

2. It does help sometimes to see these comments next to headers, but they also bring false sense of security

Yes - it would be better if the compiler was more tightly coupled to the documentation tool.

3. Doxygen is not smart enough.

OK, but Doxygen is the best tool that we have, and is still being improved. It's main weakness is controlling things that we don't want documented, but that could be improved with the will, and enthusiasm.

Otherwise all library authors are free to use trunk version of Boost.Test to try new features.

But that's a bit scary ;-) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Bjorn Reese Sent: Thursday, August 15, 2013 11:53 AM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release

On 08/15/2013 11:02 AM, Paul A. Bristow wrote:

...

OK, but Doxygen is the best tool that we have, and is still being improved.

FYI, the latest version of Doxygen can use libclang:

http://lists.cs.uiuc.edu/pipermail/cfe-dev/2013-May/029747.html

That's really good news (because Doxygen is currently confused by C++ code that won't even compile ;-) But also because it should give more control over what is passed to Quickbook. The major current downside of Doxygen is getting absolutely everything in the C++ reference section. This can make a C++ reference section very cluttered (though an index can help the user find what he is looking for). I'm sure we can improve this given the will and some expert input. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com