On 8/1/07, James Hamlin <jfhamlin@gmail.com> wrote:

Hi,

I've begun using Boost.Test to construct test suites for a project, and it looks like it does a great job and is full of nice features (I really like the auto unit tests). But I have a big complaint: the documentation is pretty poor. I had a hard time getting a simple example off the ground, because it wasn't clear that I had to link to parts of the library. This was a surprise since most of Boost is templated and so is available entirely through the headers. I had to dig a bit to find the comment about the header that includes the main() code and other concrete functions. In addition, many of the examples are missing, and some of those that are available require the linking I mentioned but fail to note this, adding to my initial confusion. Lastly, the English grammar is very rough in parts, and while I understand that English may not be the primary language of the author, it can be a big hurdle to get started using the library when one has to grapple with the documentation to understand the intentions of the author. I don't mean to rant - the library is great, and I've already found it useful - but I'd love to get more out of it, and clean, clear, and thorough documentation will get me and others started with much less head scratching and frustration.

I have also found problems with Boost.Test's documentation. For example, 5 out of the 8 complete examples (http://boost.org/libs/test/doc/examples/index.html ) are dead links, and there are serious spelling mistakes in the NYE resolution example ((http://boost.org/libs/test/doc/tutorials/new_year_resolution.html ). BOOST_AUTO_EST_CASE will never compile; it should be BOOST_AUTO_TEST_CASE. This had me scratching my head for a while, I thought it might've been short for 'establish' which made sense at the time... I had to hunt through a few headers to find the declaration before I could get my tests working.

Once I got past this though, it was all good :)

Richard

Sincerely,
James Hamlin

Postscript: This is Boost-users, but I assume Gennadiy Rozental or somebody else with the knowledge and ability to update the documentation will see this message.

_______________________________________________
Boost-users mailing list
Boost-users@lists.boost.org
http://lists.boost.org/mailman/listinfo.cgi/boost-users