[boost] Re: string_algo Formal Review

From: David Abrahams (dave_at_[hidden])
Date: 2003-10-22 08:40:17

Pavol Droba <droba_at_[hidden]> writes:

> On Tue, Oct 21, 2003 at 04:37:06PM -0400, David Abrahams wrote:
>> Pavol Droba <droba_at_[hidden]> writes:
>
> [snip]
>  
>> You can define a shorthand which associates template parameter names
>> (e.g. InputIterator) with specific concept requirements (e.g. "must
>> be an input iterator).  I think the standard does this, in fact.
>
> This is already done for iterators. I will change it for containers too.
>
>
>> You can also make some blanket statements about exceptions, like the
>> standard does.
>
> string_algo library does not throw any exceptions on its own. Only inherited
> types used by algorithms can do it. But, given the fact that most algorithms
> are templated, it is not possibly to exactly specify which exception
> can be thrown.
>
> So wouldn't it be enought to mention this as a one paragraph in docs?

Probably not quite enough.  It may be important to note that certain
functions give the strong or nothrow guarantee.  If you don't know how
to decide which those are, see
http://www.boost.org/more/generic_exception_safety.html.  If you are
still unsure, please ask for help.

>> That leaves you with only preconditions and postconditions, and
>> exceptions to the blanket statements about exceptions <g> where
>> appropriate.
>
> Is the formal specification of pre/post conditions realy so vital
> for the usage of the library? 

Normally, yes.

> Informal specification is given in paramter and result descriptions.

Can you give an example of an informal specification of
pre/post-conditions which ought to be enough?

I should point out that originality is not a virtue when it comes to
documentation conventions.  Even if your informal description does in
fact give all the neccessary information, following the formula set
out by the standard and some Boost libraries helps reviewers to
evaluate that you have done so, and will help users familiar with
those conventions to grasp your library's semantics.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com