Boost logo

Boost :

Subject: Re: [boost] [Block Pointer] make_block
From: Gregory Crosswhite (gcross_at_[hidden])
Date: 2011-05-03 21:32:05


On 05/03/2011 06:01 PM, Phil Bouchard wrote:
> On 5/3/2011 2:54 PM, GMan wrote:
>>
>> How do you know that?
>
> The tests it went through cover pretty much most of the possible
> problems.
>
>> That's the issue here; you don't, and cannot until you leave time for
>> people
>> to take a look at it and comment. But it seems you assume after every
>> fix
>> that'll be the last one. :)
>
> This time is official. There might be an issue I still need to take a
> look at in a multi-threaded mode but in a single threaded mode
> everything is guaranteed to work well, or you'll have your money back ;)
>
>
> -Phil
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost

Then I will repeat what I said before and say that you really need to
flesh out the documentation a whole lot before submitting it for a full
review. At the moment the documentation is very user unfriendly,
consisting mostly of a technical description of the ideas behind the
implementation with basically the minimum number of token examples
thrown in so that you could check a box saying that you included
documentation explaining its usage. To get a sense of what you should
be striving for, you should look at the documentation for some of the
other Boost libraries such as Boost.Thread. One thing that I like about
the documentation of Boost.Thread is that the reference documentation is
structured in such a way that you can read through from beginning to end
to learn about the full functionality of the library, which contrasts
with your Doxygen-generated reference documentation which only helps
those who know what they are looking for, and in particular contains
what looks to me like both interface and implementation details so it is
a bit overwhelming to a user who already doesn't know what is going on
due to the sparseness of documentation everywhere else.

I really want to emphasize this again since it is so important: a user
considering using your library is not going to care about all of the
fancy technical details behind it, he or she will want to know what
kinds of problems it solves and how specifically it can be used to solve
them, and you spend almost no time talking about this. Your library can
be the greatest piece of code in the world but if it takes forever for
anyone to learn how to use it then nobody will bother because there are
plenty of "good enough" libraries out there that don't require as much
trouble.

Cheers,
Greg


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