Documenting and checking template parameters
I am just refactoring the venerable circular_buffer documentation. 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? Questions: 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 ? http://www.boost.org/doc/libs/1_53_0/libs/concept_check/concept_check.htm ? Should these concepts be checked using BOOST_STATIC_ASSERT? Should *All* these be checked, even though not required for all uses? Suggestions welcome. Thanks Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
2013/5/26 Paul A. Bristow
Should these concepts be checked using BOOST_STATIC_ASSERT?
Using BOOST_STATIC_ASSERT_MSG inside of concept checking may give much readable error messages than current approach. `MoveConstructible` concept is also required. Looks like Boost.Concept library requires updating. It would be great to have ability to use Boost.TypeTraits in concept checking. -- Best regards, Antony Polukhin
On May 26, 2013, at 5:14 AM, "Paul A. Bristow"
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)
participants (3)
-
Antony Polukhin -
Paul A. Bristow -
Rob Stewart