Re: [boost] [Block Pointer] make_block

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