Jeffrey Walton writes:

It would be incredibly helpful if the project offered a few real life sample of things such as a program (with a `main`), a static archive, and a DSO (or DLL). Nothing fancy - build a DSO via a makefile with two source files (A.cpp and B.cpp) and test them (A-test.cpp and B-test.cpp). In addition, a Visual Studio project to do the same would help the Win32 folks.

I am not quite sure what exactly you are looking here. If you looking for building instructions for standalone UTF library they are covered in documentation in general, but specifically will depend on make system you are using. I'd recommend though to start with included usage variant to eliminate any building/linking overhead.

I've heard a lot of great things about Boost, and I am glad it has worked for some folks. But after a couple of days on and off with Boost::Test, I'm beginning to wonder if its a good choice for our C++ project.

aside form build is there any other specific issues?

The Boost::Test library lacks clear and concise documentation (the online documentation is fractured, lack clarity, is hard to follow, and has broken links).

I'm sorry you do not like the way documentation is structured. What would you prefer it to look like? which particular parts you find unclear?

The library is clearly abusing macros in a C++ library

Can you show me an example of this abuse? And how would achieve the same result without using them?

(where are the predicates, functors, and other things I expect to see from a C++ library? Bjarne would probably chuckle or laugh).

I can't claim what Bjarne is doing or would do, but I did laugh when I read your statement above.

And the missing samples [broken links] are really not forgivable.

I did not look at docs for quite some time. It is indeed possible some links gone stale. I need to revive the toolchain we use to generate docs and I'll fix these. Gennadiy

On Sun, Aug 7, 2011 at 6:37 AM, Ovanes Markarian wrote:

Hello *, below are my 5 cents regarding the docs and other points...

On Sun, Aug 7, 2011 at 8:41 AM, Gennadiy Rozental wrote:

...

Jeffrey Walton writes:

[...] I'm sorry you do not like the way documentation is structured. What would you prefer it to look like? which particular parts you find unclear?

The only point I can come up with, might be some shortcuts to recently used topics and these are:   - Runtime configuration parameters   - Testing tools. On the other hand I just did these 2 shortcuts in my browser.

...

...

The library is clearly abusing macros in a C++ library

Can you show me an example of this abuse? And how would achieve the same result without using them?

IMO there are none. And if the op dislikes macros he can really use the plain interface of the library which is also documented and supported ;)

...

...

(where are the predicates, functors, and other things I expect to see from a C++ library? Bjarne would probably chuckle or laugh).

I can't claim what Bjarne is doing or would do, but I did laugh when I read your statement above.

I can only support your statement, Gennadiy.

...

...

And the missing samples [broken links] are really not forgivable.

I did not look at docs for quite some time. It is indeed possible some links gone stale. I need to revive the toolchain we use to generate docs and I'll fix these.

I use the latest version and everything is documented well and all links I used to access were working fine. You guys are doing a great job. Pat yourselves on the back over a free beer.

Jeff

Richard writes:

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

Gennadiy Rozental spake the secret code thusly:

...

...

The Boost::Test library lacks clear and concise documentation (the online documentation is fractured, lack clarity, is hard to follow, and has broken links).

I'm sorry you do not like the way documentation is structured. What would you prefer it to look like? which particular parts you find unclear?

My complaint with the documentation is that when read linearly the semantic level of the information jumps up and down the complexity ladder repeatedly.

Indeed it's structured more by function than complexity, though some complexity order is present. For example it first covers simplest type of test cases going on to cover more advanced cases.

By this, I mean that tiny implementation details are presented before the overall picture has been established. For a

Can you give some examples?

new user, this is troublesome because I get lost in expert details before I've even seen a complete novice overview of the framework.

This is why I wrote that series of tutorials on how to write tests using Boost.Test. I'd be happy to work with you to turn this into a contribution to the documentation as a "getting started" or "user's guide" to boost.test.

As a first step plan to add a link to your tutorials somewhere in Boost.Test "getting started" section, but we can discuss actually incorporating it into Boost.Test docs. Regards, Gennadiy

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

It would be incredibly helpful if the project offered a few real life sample of things such as a program (with a `main`), a static archive, and a DSO (or DLL).

This all boils down to understanding how things are packaged in C++, which isn't really the point of the blog post. The blog post was to teach you how to start writing unit tests with Boost.Test. My target audience is primarily Windows developers, so I wanted to demonstrate good setup practices for that audience.

I've heard a lot of great things about Boost, and I am glad it has worked for some folks. But after a couple of days on and off with Boost::Test, I'm beginning to wonder if its a good choice for our C++ project.

At a former employer, we spent quite a bit of time evaluating different unit testing frameworks for C++, including a homebrew unit test framework. Boost.Test is as featureful as the rest of them, is widely available and widely used.

The Boost::Test library lacks clear and concise documentation (the online documentation is fractured, lack clarity, is hard to follow, and has broken links).

I found the documentation difficult to use as a programming guide. It serves well as a reference for advanced users. I know from personal experience that if you are an advanced user of something, it is hard to write documentation for it that is accessible to new users. It can be done, but its hard.

The library is clearly abusing macros in a C++ library (where are the predicates, functors, and other things I expect to see from a C++ library?

I would say that it is using macros, not abusing them. There is a considerable amount of boiler plate in fixtures, assertions and so-on and that boiler plate is most readily provided by a macro. Do you really want to be typing __FILE__ and __LINE__ on every assertion? There isn't any alternative to macros to supply this automatically. -- "The Direct3D Graphics Pipeline" -- DirectX 9 draft available for download http://legalizeadulthood.wordpress.com/the-direct3d-graphics-pipeline/ Legalize Adulthood! http://legalizeadulthood.wordpress.com