Re: [Boost-users] Boost.Test Documentation

From: Richard Dingwall (rdingwall_at_[hidden])
Date: 2007-08-02 01:02:52

On 8/1/07, James Hamlin <jfhamlin_at_[hidden]> 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_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-users
>