Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r84881 - trunk/boost/circular_buffer
From: pbristow_at_[hidden]
Date: 2013-06-22 09:43:44

Next message: andrey.semashev_at_[hidden]: "[Boost-commit] svn:boost r84882 - trunk/boost/config/compiler"
Previous message: chris_at_[hidden]: "[Boost-commit] svn:boost r84880 - trunk/libs/asio/doc"

Author: pbristow
Date: 2013-06-22 09:43:44 EDT (Sat, 22 Jun 2013)
New Revision: 84881
URL: http://svn.boost.org/trac/boost/changeset/84881

Log:
Changed Doxygen comments for new Quickbook/Doxygen based documentation. No intentional changes to code.

Text files modified:
   trunk/boost/circular_buffer/base.hpp | 44 ++++++++++++------
   trunk/boost/circular_buffer/details.hpp | 9 ++-
   trunk/boost/circular_buffer/space_optimized.hpp | 93 +++++++++++++++++++++++++--------------
   3 files changed, 93 insertions(+), 53 deletions(-)

Modified: trunk/boost/circular_buffer/base.hpp
==============================================================================
--- trunk/boost/circular_buffer/base.hpp Sat Jun 22 09:02:21 2013 (r84880)
+++ trunk/boost/circular_buffer/base.hpp 2013-06-22 09:43:44 EDT (Sat, 22 Jun 2013) (r84881)
@@ -1,6 +1,8 @@
// Implementation of the base circular buffer.

// Copyright (c) 2003-2008 Jan Gaspar
+// Copyright (c) 2013 Paul A. Bristow // Doxygen comments changed.
+

// Use, modification, and distribution is subject to the Boost Software
// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
@@ -45,19 +47,19 @@
/*!
 \class circular_buffer
 \brief Circular buffer - a STL compliant container.
- \param T The type of the elements stored in the <code>circular_buffer</code>.
+ \tparam T The type of the elements stored in the <code>circular_buffer</code>.
 \par Type Requirements T
 The <code>T</code> has to be <a href="http://www.sgi.com/tech/stl/Assignable.html">
- SGIAssignable</a> (SGI STL defined combination of <a href="../../utility/Assignable.html">
- Assignable</a> and CopyConstructible).
+ SGIAssignable</a> (SGI STL defined combination of <a href="../../../utility/Assignable.html">
+ Assignable</a> and CopyConstructible).
 Moreover <code>T</code> has to be <a href="http://www.sgi.com/tech/stl/DefaultConstructible.html">
 DefaultConstructible</a> if supplied as a default parameter when invoking some of the
 <code>circular_buffer</code>'s methods e.g.
 <code>insert(iterator pos, const value_type& item = %value_type())</code>. And
 <a href="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a> and/or
- LessThanComparable if the <code>circular_buffer</code>
+ LessThanComparable if the <code>circular_buffer</code>
 will be compared with another container.
- \param Alloc The allocator type used for all internal memory management.
+ \tparam Alloc The allocator type used for all internal memory management.
 \par Type Requirements Alloc
 The <code>Alloc</code> has to meet the allocator requirements imposed by STL.
 \par Default Alloc
@@ -75,9 +77,18 @@
/*! \endcond */
{

-// Requirements
+ // Requirements
 BOOST_CLASS_REQUIRE(T, boost, SGIAssignableConcept);

+
+ //BOOST_CONCEPT_ASSERT((Assignable<T>));
+ //BOOST_CONCEPT_ASSERT((CopyConstructible<T>));
+ //BOOST_CONCEPT_ASSERT((DefaultConstructible<T>));
+
+ // Required if the circular_buffer will be compared with anther container.
+ //BOOST_CONCEPT_ASSERT((EqualityComparable<T>));
+ //BOOST_CONCEPT_ASSERT((LessThanComparable<T>));
+
public:
// Basic types

@@ -145,9 +156,11 @@

 //! The capacity type.
 /*!
- (Same as <code>size_type</code> - defined for consistency with the
- circular_buffer_space_optimized.)
+ (Same as <code>size_type</code> - defined for consistency with the __cbso class.
+
 */
+ // circular_buffer_space_optimized.)
+
 typedef size_type capacity_type;

// Helper types
@@ -508,8 +521,9 @@
 The internal representation is often not linear and the state of the internal buffer may look like this: 
 <code>
 |e|f|g| | | |a|b|c|d| 
- end ---^ 
- begin -------^</code> 
+ end ___^ 
+ begin _______^</code> 
+
 where <code>|a|b|c|d|</code> represents the "array one", <code>|e|f|g|</code> represents the "array two" and
 <code>| | | |</code> is a free space. 
 Now consider a typical C style function for writing data into a file: 
@@ -840,7 +854,7 @@
 new capacity then number of <code>[size() - new_capacity]</code> last elements will be removed and
 the new size will be equal to <code>new_capacity</code>.
 \param new_capacity The new capacity.
- \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is
+ \throws "An allocation error" if memory is exhausted, (<code>std::bad_alloc</code> if the standard allocator is
 used).
 \throws Whatever <code>T::T(const T&)</code> throws.
 \par Exception Safety
@@ -1556,7 +1570,7 @@
 Consider a <code>circular_buffer</code> with the capacity of 6 and the size of 4. Its internal buffer may
 look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting 5 elements at the position <code>p</code>: 
+ <code>p ___^</code> After inserting 5 elements at the position <code>p</code>: 
 <code>insert(p, (size_t)5, 0);</code> actually only 4 elements get inserted and elements
 <code>1</code> and <code>2</code> are overwritten. This is due to the fact the insert operation preserves
 the capacity. After insertion the internal buffer looks like this: <code>|0|0|0|0|3|4|</code> 
@@ -1611,7 +1625,7 @@
 Consider a <code>circular_buffer</code> with the capacity of 6 and the size of 4. Its internal buffer may
 look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting a range of elements at the position <code>p</code>: 
+ <code>p ___^</code> After inserting a range of elements at the position <code>p</code>: 
 <code>int array[] = { 5, 6, 7, 8, 9 };</code> <code>insert(p, array, array + 5);</code> 
 actually only elements <code>6</code>, <code>7</code>, <code>8</code> and <code>9</code> from the
 specified range get inserted and elements <code>1</code> and <code>2</code> are overwritten. This is due
@@ -1728,7 +1742,7 @@
 Consider a <code>circular_buffer</code> with the capacity of 6 and the size of 4. Its internal buffer may
 look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting 5 elements before the position <code>p</code>: 
+ <code>p ___^</code> After inserting 5 elements before the position <code>p</code>: 
 <code>rinsert(p, (size_t)5, 0);</code> actually only 4 elements get inserted and elements
 <code>3</code> and <code>4</code> are overwritten. This is due to the fact the rinsert operation preserves
 the capacity. After insertion the internal buffer looks like this: <code>|1|2|0|0|0|0|</code> 
@@ -1775,7 +1789,7 @@
 Consider a <code>circular_buffer</code> with the capacity of 6 and the size of 4. Its internal buffer may
 look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting a range of elements before the position <code>p</code>: 
+ <code>p ___^</code> After inserting a range of elements before the position <code>p</code>: 
 <code>int array[] = { 5, 6, 7, 8, 9 };</code> <code>insert(p, array, array + 5);</code> 
 actually only elements <code>5</code>, <code>6</code>, <code>7</code> and <code>8</code> from the
 specified range get inserted and elements <code>3</code> and <code>4</code> are overwritten. This is due

Modified: trunk/boost/circular_buffer/details.hpp
==============================================================================
--- trunk/boost/circular_buffer/details.hpp Sat Jun 22 09:02:21 2013 (r84880)
+++ trunk/boost/circular_buffer/details.hpp 2013-06-22 09:43:44 EDT (Sat, 22 Jun 2013) (r84881)
@@ -137,18 +137,19 @@
template <class Size>
class capacity_control {

- //! The capacity of the space optimized circular buffer.
+ //! The capacity of the space-optimized circular buffer.
 Size m_capacity;

- //! The lowest guaranteed capacity of the adapted circular buffer.
+ //! The lowest guaranteed or minimum capacity of the adapted space-optimized circular buffer.
 Size m_min_capacity;

public:

 //! Constructor.
 capacity_control(Size buffer_capacity, Size min_buffer_capacity = 0)
- : m_capacity(buffer_capacity), m_min_capacity(min_buffer_capacity) {
- BOOST_CB_ASSERT(buffer_capacity >= min_buffer_capacity); // check for capacity lower than min_capacity
+ : m_capacity(buffer_capacity), m_min_capacity(min_buffer_capacity)
+ { // Check for capacity lower than min_capacity.
+ BOOST_CB_ASSERT(buffer_capacity >= min_buffer_capacity);
 }

 // Default copy constructor.

Modified: trunk/boost/circular_buffer/space_optimized.hpp
==============================================================================
--- trunk/boost/circular_buffer/space_optimized.hpp Sat Jun 22 09:02:21 2013 (r84880)
+++ trunk/boost/circular_buffer/space_optimized.hpp 2013-06-22 09:43:44 EDT (Sat, 22 Jun 2013) (r84881)
@@ -1,6 +1,7 @@
// Implementation of the circular buffer adaptor.

// Copyright (c) 2003-2008 Jan Gaspar
+// Copyright (c) 2013 Paul A. Bristow // Doxygen comments changed for new version of documentation.

// Use, modification, and distribution is subject to the Boost Software
// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
@@ -21,9 +22,6 @@
/*!
 \class circular_buffer_space_optimized
 \brief Space optimized circular buffer container adaptor.
-
- For detailed documentation of the space_optimized_circular_buffer visit:
- http://www.boost.org/libs/circular_buffer/doc/space_optimized.html
*/
template <class T, class Alloc>
class circular_buffer_space_optimized :
@@ -53,27 +51,50 @@
 typedef typename circular_buffer<T, Alloc>::param_value_type param_value_type;
 typedef typename circular_buffer<T, Alloc>::return_value_type return_value_type;

- //! Capacity controller of the space optimized circular buffer.
- /*!
- <pre>
-class capacity_control {
- size_type m_capacity;
- size_type m_min_capacity;
-public:
- capacity_control(size_type capacity, size_type min_capacity = 0) : m_capacity(capacity), m_min_capacity(min_capacity) {};
- size_type %capacity() const { return m_capacity; }
- size_type min_capacity() const { return m_min_capacity; }
- operator size_type() const { return m_capacity; }
-};</pre>
- \pre <code>capacity >= min_capacity</code>
- The <code>capacity()</code> represents the capacity of the <code>circular_buffer_space_optimized</code> and
- the <code>min_capacity()</code> determines the minimal allocated size of its internal buffer.
- The converting constructor of the <code>capacity_control</code> allows implicit conversion from
- <code>size_type</code>-like types which ensures compatibility of creating an instance of the
- <code>circular_buffer_space_optimized</code> with other STL containers. On the other hand the operator
- <code>%size_type()</code> provides implicit conversion to the <code>size_type</code> which allows to treat the
- capacity of the <code>circular_buffer_space_optimized</code> the same way as in the
- <code>circular_buffer</code>.
+/* <pre> is not passed through to html or pdf. So is used in code section below. Ugly :-(
+Ideally want a link to capacity_control, but this would require include details
+and this would expose all the functions in details.
+There must be a better way of doing this.
+*/
+
+ /*! Capacity controller of the space optimized circular buffer.
+
+ \see capacity_control in details.hpp.
+
+<code>
+class capacity_control 
+{ 
+ size_type m_capacity; // Available capacity. 
+ size_type m_min_capacity; // Minimum capacity. 
+public: 
+ capacity_control(size_type capacity, size_type min_capacity = 0) 
+ : m_capacity(capacity), m_min_capacity(min_capacity) 
+ {}; 
+ size_type %capacity() const { return m_capacity; } 
+ size_type min_capacity() const { return m_min_capacity; } 
+ operator size_type() const { return m_capacity; } 
+}; 
+</code>
+
+
+
+ Always
+ <code>capacity >= min_capacity</code>.
+ 
+ 
+ The <code>capacity()</code> represents the capacity
+ of the <code>circular_buffer_space_optimized</code> and
+ the <code>min_capacity()</code> determines the minimal allocated size of its internal buffer.
+ 
+ The converting constructor of the <code>capacity_control</code> allows implicit conversion from
+ <code>size_type</code>-like types which ensures compatibility of creating an instance of the
+ <code>circular_buffer_space_optimized</code> with other STL containers.
+
+ On the other hand the operator <code>%size_type()</code>
+ provides implicit conversion to the <code>size_type</code> which allows to treat the
+ capacity of the <code>circular_buffer_space_optimized</code> the same way as in the
+ <code>circular_buffer</a></code>.
+
 */
 typedef cb_details::capacity_control<size_type> capacity_type;

@@ -178,7 +199,7 @@
 than the new capacity then the amount of allocated memory in the internal buffer may be accommodated as
 necessary but it will never drop below <code>capacity_ctrl.min_capacity()</code>.
 \param capacity_ctrl The new capacity controller.
- \throws "An allocation error" if memory is exhausted (<code>std::bad_alloc</code> if the standard allocator is
+ \throws "An allocation error" if memory is exhausted, (<code>std::bad_alloc</code> if the standard allocator is
 used).
 \throws Whatever <code>T::T(const T&)</code> throws.
 \par Exception Safety
@@ -692,7 +713,7 @@
 circular_buffer<T, Alloc>::assign(capacity_ctrl, first, last);
 }

- //! Swap the contents of two space optimized circular buffers.
+ //! Swap the contents of two space-optimized circular-buffers.
 /*!
 \post <code>this</code> contains elements of <code>cb</code> and vice versa; the capacity and the amount of
 allocated memory in the internal buffer of <code>this</code> equal to the capacity and the amount of
@@ -704,13 +725,17 @@
 \par Iterator Invalidation
 Invalidates all iterators of both <code>circular_buffer_space_optimized</code> containers. (On the other
 hand the iterators still point to the same elements but within another container. If you want to rely on
- this feature you have to turn the Debug Support off otherwise an
- assertion will report an error if such invalidated iterator is used.)
+ this feature you have to turn the __debug_support off by defining macro BOOST_CB_DISABLE_DEBUG,
+ otherwise an assertion will report an error if such invalidated iterator is used.)
 \par Complexity
 Constant (in the size of the <code>circular_buffer_space_optimized</code>).
 \sa <code>\link swap(circular_buffer<T, Alloc>&, circular_buffer<T, Alloc>&)
 swap(circular_buffer_space_optimized<T, Alloc>&, circular_buffer_space_optimized<T, Alloc>&)\endlink</code>
+
+
 */
+ // Note link does not work right. Asked on Doxygen forum for advice 23 May 2103.
+
 void swap(circular_buffer_space_optimized<T, Alloc>& cb) {
 std::swap(m_capacity_ctrl, cb.m_capacity_ctrl);
 circular_buffer<T, Alloc>::swap(cb);
@@ -876,7 +901,7 @@
 Consider a <code>circular_buffer_space_optimized</code> with the capacity of 6 and the size of 4. Its
 internal buffer may look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting 5 elements at the position <code>p</code>: 
+ <code>p ___^</code> After inserting 5 elements at the position <code>p</code>: 
 <code>insert(p, (size_t)5, 0);</code> actually only 4 elements get inserted and elements
 <code>1</code> and <code>2</code> are overwritten. This is due to the fact the insert operation preserves
 the capacity. After insertion the internal buffer looks like this: <code>|0|0|0|0|3|4|</code> 
@@ -927,7 +952,7 @@
 Consider a <code>circular_buffer_space_optimized</code> with the capacity of 6 and the size of 4. Its
 internal buffer may look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting a range of elements at the position <code>p</code>: 
+ <code>p ___^</code> After inserting a range of elements at the position <code>p</code>: 
 <code>int array[] = { 5, 6, 7, 8, 9 };</code> <code>insert(p, array, array + 5);</code> 
 actually only elements <code>6</code>, <code>7</code>, <code>8</code> and <code>9</code> from the
 specified range get inserted and elements <code>1</code> and <code>2</code> are overwritten. This is due
@@ -1012,7 +1037,7 @@
 Consider a <code>circular_buffer_space_optimized</code> with the capacity of 6 and the size of 4. Its
 internal buffer may look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting 5 elements before the position <code>p</code>: 
+ <code>p ___^</code> After inserting 5 elements before the position <code>p</code>: 
 <code>rinsert(p, (size_t)5, 0);</code> actually only 4 elements get inserted and elements
 <code>3</code> and <code>4</code> are overwritten. This is due to the fact the rinsert operation preserves
 the capacity. After insertion the internal buffer looks like this: <code>|1|2|0|0|0|0|</code> 
@@ -1064,7 +1089,7 @@
 Consider a <code>circular_buffer_space_optimized</code> with the capacity of 6 and the size of 4. Its
 internal buffer may look like the one below. 
 <code>|1|2|3|4| | |</code> 
- <code>p ---^</code> After inserting a range of elements before the position <code>p</code>: 
+ <code>p ___^</code> After inserting a range of elements before the position <code>p</code>: 
 <code>int array[] = { 5, 6, 7, 8, 9 };</code> <code>insert(p, array, array + 5);</code> 
 actually only elements <code>5</code>, <code>6</code>, <code>7</code> and <code>8</code> from the
 specified range get inserted and elements <code>3</code> and <code>4</code> are overwritten. This is due
@@ -1162,7 +1187,7 @@
 \par Complexity
 Linear (in the size of the <code>circular_buffer_space_optimized</code>).
 \note Basically there is no difference between <code>erase(iterator)</code> and this method. It is implemented
- only for consistency with the base <code>circular_buffer</code>.
+ only for consistency with the base <code>circular_buffer</code>.
 \sa <code>erase(iterator)</code>, <code>erase(iterator, iterator)</code>,
 <code>rerase(iterator, iterator)</code>, <code>clear()</code>
 */
@@ -1195,7 +1220,7 @@
 Linear (in the size of the <code>circular_buffer_space_optimized</code>).
 \note Basically there is no difference between <code>erase(iterator, iterator)</code> and this method. It is
 implemented only for consistency with the base
- <code>circular_buffer</code>.
+ <code><circular_buffer</code>.
 \sa <code>erase(iterator)</code>, <code>erase(iterator, iterator)</code>, <code>rerase(iterator)</code>,
 <code>clear()</code>
 */

Next message: andrey.semashev_at_[hidden]: "[Boost-commit] svn:boost r84882 - trunk/boost/config/compiler"
Previous message: chris_at_[hidden]: "[Boost-commit] svn:boost r84880 - trunk/libs/asio/doc"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk