Re: [boost] Documenting and checking template parameters

Subject: Re: [boost] Documenting and checking template parameters
From: Rob Stewart (robertstewart_at_[hidden])
Date: 2013-05-26 18:15:33

On May 26, 2013, at 5:14 AM, "Paul A. Bristow" <pbristow_at_[hidden]> wrote:

> The docs describe the Template parameter T  and specify it thus:
> 
> The type of the elements stored in the circular_buffer. The T has to be SGIAssignable (SGI STL
> defined combination of Assignable and CopyConstructible). 
> 
> Moreover T has to be DefaultConstructible if supplied as a default parameter when invoking some of the circular_buffer's methods e.g. insert(iterator pos, const value_type& item = value_type()). 
> 
> And EqualityComparable and/or LessThanComparable if the circular_buffer will be compared with another container.
> 
> This looks a bit out of date?

Yes

> How should a parameter like this *best* be described in documentation and enforced in software?
> 
> http://www.boost.org/doc/libs/1_53_0/doc/html/Assignable.html ?

I presume swap() is only needed in circular_buffer's swap().

> http://www.boost.org/doc/libs/1_53_0/libs/concept_check/concept_check.htm ?

Using BCCL is very handy, but...

> Should these concepts be checked using BOOST_STATIC_ASSERT?

...that's fine, too.

> Should *All* these be checked, even though not required for all uses?

Only CopyConstructible and CopyAssignable are required to create and use a circular_buffer, so those are all that you should list as required. I'd add that a few operations require more of T, and that those extra requirements are documented with those operations.

You could link to all of those operations, or list the requirements for each of those operations up front, so a potential user can get a complete picture. The former involves slightly less duplication.

___
Rob

(Sent from my portable computation engine)