From: khizmax <libcds.dev@gmail.com>
Date: Sat, 12 Mar 2016 08:59:23 +0000 (+0300)
Subject: Fixed docs
X-Git-Tag: v2.2.0~364
X-Git-Url: http://plrg.eecs.uci.edu/git/?a=commitdiff_plain;h=81d09ca9a060746080009db20b8f659cb02a1eac;p=libcds.git

Fixed docs
---

diff --git a/cds/intrusive/michael_set_rcu.h b/cds/intrusive/michael_set_rcu.h
index 867191e7..9157f02d 100644
--- a/cds/intrusive/michael_set_rcu.h
+++ b/cds/intrusive/michael_set_rcu.h
@@ -156,7 +156,7 @@ namespace cds { namespace intrusive {
         //@endcond
 
     public:
-    ///@name Forward iterators (thread-safe only under RCU lock)
+    ///@name Forward iterators (thread-safe under RCU lock)
     //@{
         /// Forward iterator
         /**
diff --git a/cds/intrusive/split_list.h b/cds/intrusive/split_list.h
index 9a7e198e..1316360f 100644
--- a/cds/intrusive/split_list.h
+++ b/cds/intrusive/split_list.h
@@ -1135,6 +1135,8 @@ namespace cds { namespace intrusive {
         };
         //@endcond
     public:
+    ///@name Forward iterators (only for debugging purpose)
+    //@{
         /// Forward iterator
         /**
             The forward iterator for a split-list has some features:
@@ -1142,12 +1144,13 @@ namespace cds { namespace intrusive {
             - it depends on iterator of underlying \p OrderedList
             - The iterator cannot be moved across thread boundary since it may contain 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.
+              deleting operations it is no guarantee that you iterate all item in the set.
+              Moreover, a crash is possible when you try to iterate the next element that has been deleted by concurrent thread.
 
-            Therefore, the use of iterators in concurrent environment is not good idea. Use the iterator on the concurrent container
-            for debug purpose only.
+            @warning Use this iterator on the concurrent container for debugging purpose only.
         */
         typedef iterator_type<false>    iterator;
+
         /// Const forward iterator
         /**
             For iterator's features and requirements see \ref iterator
@@ -1196,7 +1199,7 @@ namespace cds { namespace intrusive {
         {
             return const_iterator( m_List.cend(), m_List.cend());
         }
-
+    //@}
     };
 
 }}  // namespace cds::intrusive
diff --git a/cds/intrusive/split_list_nogc.h b/cds/intrusive/split_list_nogc.h
index f1077513..3784d5a8 100644
--- a/cds/intrusive/split_list_nogc.h
+++ b/cds/intrusive/split_list_nogc.h
@@ -542,6 +542,8 @@ namespace cds { namespace intrusive {
         //@endcond
 
     public:
+    ///@name Forward iterators
+    //@{
         /// Forward iterator
         /**
             The forward iterator for a split-list has some features:
@@ -549,6 +551,7 @@ namespace cds { namespace intrusive {
             - it depends on iterator of underlying \p OrderedList
         */
         typedef iterator_type<false>    iterator;
+
         /// Const forward iterator
         /**
             For iterator's features and requirements see \ref iterator
@@ -577,28 +580,29 @@ namespace cds { namespace intrusive {
         }
 
         /// Returns a forward const iterator addressing the first element in a split-list
-        //@{
         const_iterator begin() const
         {
             return const_iterator( m_List.begin(), m_List.end() );
         }
+
+        /// Returns a forward const iterator addressing the first element in a split-list
         const_iterator cbegin() const
         {
             return const_iterator( m_List.cbegin(), m_List.cend() );
         }
-        //@}
 
         /// Returns an const iterator that addresses the location succeeding the last element in a split-list
-        //@{
         const_iterator end() const
         {
             return const_iterator( m_List.end(), m_List.end() );
         }
+
+        /// Returns an const iterator that addresses the location succeeding the last element in a split-list
         const_iterator cend() const
         {
             return const_iterator( m_List.cend(), m_List.cend() );
         }
-        //@}
+    //@}
 
     protected:
         //@cond
diff --git a/cds/intrusive/split_list_rcu.h b/cds/intrusive/split_list_rcu.h
index 94088046..0159b6e1 100644
--- a/cds/intrusive/split_list_rcu.h
+++ b/cds/intrusive/split_list_rcu.h
@@ -1025,17 +1025,16 @@ namespace cds { namespace intrusive {
         //@endcond
 
     public:
+    ///@name Forward iterators (thread-safe under RCU lock)
+    //@{
         /// Forward iterator
         /**
             The forward iterator for a split-list has some features:
             - it has no post-increment operator
             - it depends on iterator of underlying \p OrderedList
-            - The iterator cannot be moved across thread boundary since it may contain 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 the iterator on the concurrent container
-            for debug purpose only.
+            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.
         */
         typedef iterator_type<false>    iterator;
         /// Const forward iterator
@@ -1086,7 +1085,7 @@ namespace cds { namespace intrusive {
         {
             return const_iterator( m_List.cend(), m_List.cend() );
         }
-
+    //@}
     };
 
 }}  // namespace cds::intrusive