Merge #655

655: Add docs for SkipSet and SkipList r=jeehoonkang a=taiki-e

This is the main blocker for the crossbeam-skiplist 0.1 release.

cc #635 



Co-authored-by: Taiki Endo <te316e89@gmail.com>

crossbeam-skiplist/src/base.rs

@@ -1,4 +1,4 @@
-//! TODO: docs
+//! A lock-free skip list. See [`SkipList`].
 
 use alloc::alloc::{alloc, dealloc, handle_alloc_error, Layout};
 use core::borrow::Borrow;
@@ -1551,6 +1551,7 @@ where
             }
         }
     }
+
     /// Moves to the previous entry in the skip list.
     pub fn move_prev(&mut self, guard: &Guard) -> bool {
         match self.prev(guard) {
@@ -1684,7 +1685,7 @@ impl<'a, K: 'a, V: 'a> RefIter<'a, K, V>
 where
     K: Ord,
 {
-    /// TODO
+    /// Advances the iterator and returns the next value.
     pub fn next(&mut self, guard: &Guard) -> Option<RefEntry<'a, K, V>> {
         self.parent.check_guard(guard);
         self.head = match self.head {
@@ -1710,7 +1711,7 @@ where
         self.head.clone()
     }
 
-    /// TODO
+    /// Removes and returns an element from the end of the iterator.
     pub fn next_back(&mut self, guard: &Guard) -> Option<RefEntry<'a, K, V>> {
         self.parent.check_guard(guard);
         self.tail = match self.tail {
@@ -1888,7 +1889,7 @@ where
     R: RangeBounds<Q>,
     Q: Ord + ?Sized,
 {
-    /// TODO
+    /// Advances the iterator and returns the next value.
     pub fn next(&mut self, guard: &Guard) -> Option<RefEntry<'a, K, V>> {
         self.parent.check_guard(guard);
         self.head = match self.head {
@@ -1912,7 +1913,7 @@ where
         self.head.clone()
     }
 
-    /// TODO: docs
+    /// Removes and returns an element from the end of the iterator.
     pub fn next_back(&mut self, guard: &Guard) -> Option<RefEntry<'a, K, V>> {
         self.parent.check_guard(guard);
         self.tail = match self.tail {

crossbeam-skiplist/src/lib.rs

@@ -6,7 +6,7 @@
 //! multiple threads.
 //!
 //! # Concurrent access
-//! [`SkipMap`] and [`SkipSet`] implement `Send` and `Sync`,
+//! [`SkipMap`] and [`SkipSet`] implement [`Send`] and [`Sync`],
 //! so they can be shared across threads with ease.
 //!
 //! Methods which mutate the map, such as [`insert`],

crossbeam-skiplist/src/map.rs

@@ -22,6 +22,14 @@ pub struct SkipMap<K, V> {
 
 impl<K, V> SkipMap<K, V> {
     /// Returns a new, empty map.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use crossbeam_skiplist::SkipMap;
+    ///
+    /// let map: SkipMap<i32, &str> = SkipMap::new();
+    /// ```
     pub fn new() -> SkipMap<K, V> {
         SkipMap {
             inner: base::SkipList::new(epoch::default_collector().clone()),
@@ -83,8 +91,8 @@ where
     ///
     /// let numbers = SkipMap::new();
     /// numbers.insert(5, "five");
+    /// assert_eq!(*numbers.front().unwrap().value(), "five");
     /// numbers.insert(6, "six");
-    ///
     /// assert_eq!(*numbers.front().unwrap().value(), "five");
     /// ```
     pub fn front(&self) -> Option<Entry<'_, K, V>> {
@@ -103,8 +111,8 @@ where
     ///
     /// let numbers = SkipMap::new();
     /// numbers.insert(5, "five");
+    /// assert_eq!(*numbers.back().unwrap().value(), "five");
     /// numbers.insert(6, "six");
-    ///
     /// assert_eq!(*numbers.back().unwrap().value(), "six");
     /// ```
     pub fn back(&self) -> Option<Entry<'_, K, V>> {
@@ -274,9 +282,9 @@ where
         }
     }
 
-    /// Returns an iterator over a subset of entries in the skip list.
+    /// Returns an iterator over a subset of entries in the map.
     ///
-    ///  This iterator returns [`Entry`]s which
+    /// This iterator returns [`Entry`]s which
     /// can be used to access keys and their associated values.
     ///
     /// # Example
@@ -381,7 +389,7 @@ where
     /// assert_eq!(*numbers.pop_front().unwrap().value(), "twelve");
     ///
     /// // All entries have been removed now.
-    /// assert!(numbers.pop_front().is_none());
+    /// assert!(numbers.is_empty());
     /// ```
     pub fn pop_front(&self) -> Option<Entry<'_, K, V>> {
         let guard = &epoch::pin();
@@ -408,7 +416,7 @@ where
     /// assert_eq!(*numbers.pop_back().unwrap().value(), "six");
     ///
     /// // All entries have been removed now.
-    /// assert!(numbers.pop_front().is_none());
+    /// assert!(numbers.is_empty());
     /// ```
     pub fn pop_back(&self) -> Option<Entry<'_, K, V>> {
         let guard = &epoch::pin();
@@ -641,7 +649,7 @@ impl<K, V> fmt::Debug for Iter<'_, K, V> {
     }
 }
 
-/// An iterator over the entries of a `SkipMap`.
+/// An iterator over a subset of entries of a `SkipMap`.
 pub struct Range<'a, Q, R, K, V>
 where
     K: Ord + Borrow<Q>,