From 4eb140d44e7c644deb0220d0b27260598a4fb9b9 Mon Sep 17 00:00:00 2001
From: khizmax <libcds.dev@gmail.com>
Date: Thu, 18 Feb 2016 22:41:20 +0300
Subject: [PATCH] Docfix

---
 cds/container/impl/michael_list.h  |  4 ++--
 cds/container/lazy_kvlist_rcu.h    | 15 +++++++++++----
 cds/container/michael_kvlist_rcu.h | 13 +++++++++----
 cds/intrusive/michael_list_rcu.h   |  8 ++++++++
 4 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/cds/container/impl/michael_list.h b/cds/container/impl/michael_list.h
index 8284aefc..287ee4b1 100644
--- a/cds/container/impl/michael_list.h
+++ b/cds/container/impl/michael_list.h
@@ -259,6 +259,8 @@ namespace cds { namespace container {
         //@endcond
 
     public:
+    ///@name Forward iterators (only for debugging purpose)
+    //@{
         /// Forward iterator
         /**
             The forward iterator for Michael's list has some features:
@@ -280,8 +282,6 @@ namespace cds { namespace container {
         */
         typedef iterator_type<true>     const_iterator;
 
-    ///@name Forward iterators (only for debugging purpose)
-    //@{
         /// Returns a forward iterator addressing the first element in a list
         /**
             For empty list \code begin() == end() \endcode
diff --git a/cds/container/lazy_kvlist_rcu.h b/cds/container/lazy_kvlist_rcu.h
index 828772b2..8fd92684 100644
--- a/cds/container/lazy_kvlist_rcu.h
+++ b/cds/container/lazy_kvlist_rcu.h
@@ -287,7 +287,13 @@ namespace cds { namespace container {
         //@endcond
 
     public:
+    ///@name Forward iterators
+    //@{
         /// Forward iterator
+        /**
+            You may safely use iterators in multi-threaded environment only under external RCU lock.
+            Otherwise, a program crash is possible if another thread deletes the item the iterator points to.
+        */
         typedef iterator_type<false>    iterator;
 
         /// Const forward iterator
@@ -318,32 +324,33 @@ namespace cds { namespace container {
         }
 
         /// Returns a forward const iterator addressing the first element in a list
-        //@{
         const_iterator begin() const
         {
             const_iterator it( head() );
             ++it;   // skip dummy head
             return it;
         }
+
+        /// Returns a forward const iterator addressing the first element in a list
         const_iterator cbegin() const
         {
             const_iterator it( head() );
             ++it;   // skip dummy head
             return it;
         }
-        //@}
 
         /// Returns an const iterator that addresses the location succeeding the last element in a list
-        //@{
         const_iterator end() const
         {
             return const_iterator( tail());
         }
+
+        /// Returns an const iterator that addresses the location succeeding the last element in a list
         const_iterator cend() const
         {
             return const_iterator( tail());
         }
-        //@}
+    //@}
 
     public:
         /// Default constructor
diff --git a/cds/container/michael_kvlist_rcu.h b/cds/container/michael_kvlist_rcu.h
index c4b48ba9..6b80b9e1 100644
--- a/cds/container/michael_kvlist_rcu.h
+++ b/cds/container/michael_kvlist_rcu.h
@@ -302,7 +302,13 @@ namespace cds { namespace container {
         //@endcond
 
     public:
+    ///@name Forward iterators
+    //@{
         /// Forward iterator
+        /**
+            You may safely use iterators in multi-threaded environment only under external RCU lock.
+            Otherwise, a program crash is possible if another thread deletes the item the iterator points to.
+        */
         typedef iterator_type<false>    iterator;
 
         /// Const forward iterator
@@ -331,28 +337,27 @@ namespace cds { namespace container {
         }
 
         /// Returns a forward const iterator addressing the first element in a list
-        //@{
         const_iterator begin() const
         {
             return const_iterator( head() );
         }
+        /// Returns a forward const iterator addressing the first element in a list
         const_iterator cbegin() const
         {
             return const_iterator( head() );
         }
-        //@}
 
         /// Returns an const iterator that addresses the location succeeding the last element in a list
-        //@{
         const_iterator end() const
         {
             return const_iterator();
         }
+        /// Returns an const iterator that addresses the location succeeding the last element in a list
         const_iterator cend() const
         {
             return const_iterator();
         }
-        //@}
+    //@}
 
     public:
         /// Default constructor
diff --git a/cds/intrusive/michael_list_rcu.h b/cds/intrusive/michael_list_rcu.h
index cea4f18e..ed21242b 100644
--- a/cds/intrusive/michael_list_rcu.h
+++ b/cds/intrusive/michael_list_rcu.h
@@ -371,8 +371,15 @@ namespace cds { namespace intrusive {
         //@endcond
 
     public:
+    ///@name Forward iterators (only for debugging purpose)
+    //@{
         /// Forward iterator
+        /**
+            You may safely use iterators in multi-threaded environment only under RCU lock.
+            Otherwise, a crash is possible if another thread deletes the item the iterator points to.
+        */
         typedef iterator_type<false>    iterator;
+
         /// Const forward iterator
         typedef iterator_type<true>     const_iterator;
 
@@ -419,6 +426,7 @@ namespace cds { namespace intrusive {
         {
             return const_iterator();
         }
+    //@}
 
     public:
         /// Default constructor initializes empty list
-- 
2.34.1