feat: publicly export UniqueIter (#87)

This type is returned by a public method, but it isn't publicly
re-exported. This means that it cannot currently be named in downstream
code, and the documentation for its `Iterator` implementation is not
rendered in RustDoc. This is an oversight on my part, as the type was
intended to be public.

This commit fixes that, by publicly re-exporting `UniqueIter`. In
addition, I've added some improved documentation for `UniqueIter`, which
should help users to understand its guarantees.

Fixes #77

src/iter.rs

@@ -1,6 +1,8 @@
 use crate::{page, shard};
 use std::slice;
 
+/// An exclusive iterator over the items in a [`Slab`](crate::Slab).
+#[must_use = "iterators are lazy and do nothing unless consumed"]
 #[derive(Debug)]
 pub struct UniqueIter<'a, T, C: crate::cfg::Config> {
     pub(super) shards: shard::IterMut<'a, Option<T>, C>,

src/lib.rs

@@ -215,8 +215,11 @@ mod page;
 mod shard;
 mod tid;
 
-pub use cfg::{Config, DefaultConfig};
-pub use clear::Clear;
+pub use self::{
+    cfg::{Config, DefaultConfig},
+    clear::Clear,
+    iter::UniqueIter,
+};
 #[doc(inline)]
 pub use pool::Pool;
 
@@ -735,6 +738,10 @@ impl<T, C: cfg::Config> Slab<T, C> {
     }
 
     /// Returns an iterator over all the items in the slab.
+    ///
+    /// Because this iterator exclusively borrows the slab (i.e. it holds an
+    /// `&mut Slab<T>`), elements will not be added or removed while the
+    /// iteration is in progress.
     pub fn unique_iter(&mut self) -> iter::UniqueIter<'_, T, C> {
         let mut shards = self.shards.iter_mut();
         let shard = shards.next().expect("must be at least 1 shard");