Docfix

diff --git a/cds/container/split_list_set.h b/cds/container/split_list_set.h
index a68cd89d7a9fb2a3edb8b9517b22db8a6b0c0818..5003474b90f79b7a148d9d776a9484591670ab7b 100644 (file)
--- a/cds/container/split_list_set.h
+++ b/cds/container/split_list_set.h
@@ -249,26 +249,13 @@ namespace cds { namespace container {
         //@endcond
 
     protected:
-        /// Forward iterator
-        /**
-            \p IsConst - constness boolean flag
-
-            The forward iterator for a split-list has the following features:
-            - it has no post-increment operator
-            - it depends on underlying ordered list iterator
-            - The iterator object cannot be moved across thread boundary since it contains GC's guard that is thread-private GC data.
-            - Iterator ensures thread-safety even if you delete the item that iterator points to. However, in case of concurrent
-              deleting operations it is no guarantee that you iterate all item in the split-list.
-
-            Therefore, the use of iterators in concurrent environment is not good idea. Use it for debug purpose only.
-        */
+        //@cond
         template <bool IsConst>
         class iterator_type: protected base_class::template iterator_type<IsConst>
         {
-            //@cond
             typedef typename base_class::template iterator_type<IsConst> iterator_base_class;
             friend class SplitListSet;
-            //@endcond
+
         public:
             /// Value pointer type (const for const iterator)
             typedef typename cds::details::make_const_type<value_type, IsConst>::pointer   value_ptr;
@@ -286,11 +273,9 @@ namespace cds { namespace container {
             {}
 
         protected:
-            //@cond
             explicit iterator_type( iterator_base_class const& src )
                 : iterator_base_class( src )
             {}
-            //@endcond
 
         public:
             /// Dereference operator
@@ -333,6 +318,7 @@ namespace cds { namespace container {
                 return iterator_base_class::operator!=(i);
             }
         };
+        //@endcond
 
     public:
         /// Initializes split-ordered list of default capacity
@@ -354,7 +340,48 @@ namespace cds { namespace container {
         {}
 
     public:
+    ///@name Forward iterators (only for debugging purpose)
+    //@{
         /// Forward iterator
+        /**
+            The forward iterator for a split-list has the following features:
+            - it has no post-increment operator
+            - it depends on underlying ordered list iterator
+            - The iterator object cannot be moved across thread boundary because it contains GC's guard that is thread-private GC data.
+            - Iterator ensures thread-safety even if you delete the item that iterator points to. However, in case of concurrent
+              deleting operations it is no guarantee that you iterate all item in the split-list.
+              Moreover, a crash is possible when you try to iterate the next element that has been deleted by concurrent thread.
+
+              @warning Use this iterator on the concurrent container for debugging purpose only.
+
+              The iterator interface:
+              \code
+              class iterator {
+              public:
+              // Default constructor
+              iterator();
+
+              // Copy construtor
+              iterator( iterator const& src );
+
+              // Dereference operator
+              value_type * operator ->() const;
+
+              // Dereference operator
+              value_type& operator *() const;
+
+              // Preincrement operator
+              iterator& operator ++();
+
+              // Assignment operator
+              iterator& operator = (iterator const& src);
+
+              // Equality operators
+              bool operator ==(iterator const& i ) const;
+              bool operator !=(iterator const& i ) const;
+              };
+              \endcode
+        */
         typedef iterator_type<false>  iterator;
 
         /// Const forward iterator
@@ -401,6 +428,7 @@ namespace cds { namespace container {
         {
             return const_iterator( base_class::cend());
         }
+    //@}
 
     public:
         /// Inserts new node

diff --git a/cds/container/split_list_set_nogc.h b/cds/container/split_list_set_nogc.h
index 8a83494f8040149c3c49e7207cfa90d5e9a8f1ea..4b74adb3f0eee8f887f3401018c0cd6d4a9758fc 100644 (file)
--- a/cds/container/split_list_set_nogc.h
+++ b/cds/container/split_list_set_nogc.h
@@ -137,21 +137,13 @@ namespace cds { namespace container {
         {}
 
     protected:
-        /// Forward iterator
-        /**
-            \p IsConst - constness boolean flag
-
-            The forward iterator has the following features:
-            - it has no post-increment operator
-            - it depends on underlying ordered list iterator
-        */
+        //@cond
         template <bool IsConst>
         class iterator_type: protected base_class::template iterator_type<IsConst>
         {
-            //@cond
             typedef typename base_class::template iterator_type<IsConst> iterator_base_class;
             friend class SplitListSet;
-            //@endcond
+
         public:
             /// Value pointer type (const for const iterator)
             typedef typename cds::details::make_const_type<value_type, IsConst>::pointer   value_ptr;
@@ -169,11 +161,9 @@ namespace cds { namespace container {
             {}
 
         protected:
-            //@cond
             explicit iterator_type( iterator_base_class const& src )
                 : iterator_base_class( src )
             {}
-            //@endcond
 
         public:
             /// Dereference operator
@@ -216,9 +206,45 @@ namespace cds { namespace container {
                 return iterator_base_class::operator!=(i);
             }
         };
+        //@endcond
 
     public:
+    ///@name Forward iterators
+    //@{
         /// Forward iterator
+        /**
+            The forward iterator for Michael's set is based on \p OrderedList forward iterator and has some features:
+            - it has no post-increment operator
+            - it iterates items in unordered fashion
+
+            The iterator interface:
+            \code
+            class iterator {
+            public:
+                // Default constructor
+                iterator();
+
+                // Copy construtor
+                iterator( iterator const& src );
+
+                // Dereference operator
+                value_type * operator ->() const;
+
+                // Dereference operator
+                value_type& operator *() const;
+
+                // Preincrement operator
+                iterator& operator ++();
+
+                // Assignment operator
+                iterator& operator = (iterator const& src);
+
+                // Equality operators
+                bool operator ==(iterator const& i ) const;
+                bool operator !=(iterator const& i ) const;
+            };
+            \endcode
+        */
         typedef iterator_type<false>  iterator;
 
         /// Const forward iterator
@@ -265,6 +291,7 @@ namespace cds { namespace container {
         {
             return const_iterator( base_class::cend() );
         }
+    //@}
 
     protected:
         //@cond

diff --git a/cds/container/split_list_set_rcu.h b/cds/container/split_list_set_rcu.h
index cec9f0b23893604096bf346ec485e046441b463a..c2625cf96bbd6ee75346225b892098b5406f4892 100644 (file)
--- a/cds/container/split_list_set_rcu.h
+++ b/cds/container/split_list_set_rcu.h
@@ -366,26 +366,13 @@ namespace cds { namespace container {
         //@endcond
 
     protected:
-        /// Forward iterator
-        /**
-            \p IsConst - constness boolean flag
-
-            The forward iterator for a split-list has the following features:
-            - it has no post-increment operator
-            - it depends on underlying ordered list iterator
-            - it is safe to iterate only inside RCU critical section
-            - deleting an item pointed by the iterator can cause to deadlock
-
-            Therefore, the use of iterators in concurrent environment is not good idea.
-            Use it for debug purpose only.
-        */
+        //@cond
         template <bool IsConst>
         class iterator_type: protected base_class::template iterator_type<IsConst>
         {
-            //@cond
             typedef typename base_class::template iterator_type<IsConst> iterator_base_class;
             friend class SplitListSet;
-            //@endcond
+
         public:
             /// Value pointer type (const for const iterator)
             typedef typename cds::details::make_const_type<value_type, IsConst>::pointer   value_ptr;
@@ -403,11 +390,9 @@ namespace cds { namespace container {
             {}
 
         protected:
-            //@cond
             explicit iterator_type( iterator_base_class const& src )
                 : iterator_base_class( src )
             {}
-            //@endcond
 
         public:
             /// Dereference operator
@@ -450,6 +435,7 @@ namespace cds { namespace container {
                 return iterator_base_class::operator!=(i);
             }
         };
+        //@endcond
 
     public:
         /// Initializes split-ordered list of default capacity
@@ -471,8 +457,49 @@ namespace cds { namespace container {
         {}
 
     public:
-        typedef iterator_type<false>  iterator        ; ///< Forward iterator
-        typedef iterator_type<true>   const_iterator  ; ///< Forward const iterator
+    ///@name Forward iterators (thread-safe under RCU lock)
+    //@{
+        /// Forward iterator
+        /**
+            The forward iterator for Michael's set is based on \p OrderedList forward iterator and has some features:
+            - it has no post-increment operator
+            - it iterates items in unordered fashion
+
+            You may safely use iterators in multi-threaded environment only under RCU lock.
+            Otherwise, a crash is possible if another thread deletes the element the iterator points to.
+
+            The iterator interface:
+            \code
+            class iterator {
+            public:
+                // Default constructor
+                iterator();
+
+                // Copy construtor
+                iterator( iterator const& src );
+
+                // Dereference operator
+                value_type * operator ->() const;
+
+                // Dereference operator
+                value_type& operator *() const;
+
+                // Preincrement operator
+                iterator& operator ++();
+
+                // Assignment operator
+                iterator& operator = (iterator const& src);
+
+                // Equality operators
+                bool operator ==(iterator const& i ) const;
+                bool operator !=(iterator const& i ) const;
+            };
+            \endcode
+        */
+        typedef iterator_type<false>  iterator;
+
+        /// Forward const iterator
+        typedef iterator_type<true>   const_iterator;
 
         /// Returns a forward iterator addressing the first element in a set
         /**
@@ -515,6 +542,7 @@ namespace cds { namespace container {
         {
             return const_iterator( base_class::cend() );
         }
+    //@}
 
     public:
         /// Inserts new node