X-Git-Url: https://git.chrismorgan.info/anymap/blobdiff_plain/bf29e608d91175d0fca2108fd1b5d75596a4a796..2d5be08822c6b533ba40835a639ae2f0ca470ad7:/src/lib.rs?ds=sidebyside

diff --git a/src/lib.rs b/src/lib.rs
index c9e0276..31b271e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,12 +1,15 @@
-//! This crate provides the `AnyMap` type, a safe and convenient store for one value of each type.
+//! This crate provides a safe and convenient store for one value of each type.
+//!
+//! Your starting point is [`Map`]. It has an example.
 
 #![warn(missing_docs, unused_results)]
 
-use std::any::TypeId;
+use std::any::{Any, TypeId};
 use std::marker::PhantomData;
 
 use raw::RawMap;
-use any::{UncheckedAnyExt, IntoBox, Any};
+use any::{UncheckedAnyExt, IntoBox};
+pub use any::CloneAny;
 
 macro_rules! impl_common_methods {
     (
@@ -85,21 +88,36 @@ macro_rules! impl_common_methods {
     }
 }
 
-pub mod any;
+mod any;
 pub mod raw;
 
 /// A collection containing zero or one values for any given type and allowing convenient,
 /// type-safe access to those values.
 ///
 /// The type parameter `A` allows you to use a different value type; normally you will want it to
-/// be `anymap::any::Any`, but there are other choices:
+/// be `std::any::Any`, but there are other choices:
 ///
-/// - If you want the entire map to be cloneable, use `CloneAny` instead of `Any`.
-/// - You can add on `+ Send` and/or `+ Sync` (e.g. `Map<dyn Any + Send>`) to add those bounds.
+/// - If you want the entire map to be cloneable, use `CloneAny` instead of `Any`; with that, you
+///   can only add types that implement `Clone` to the map.
+/// - You can add on `+ Send` or `+ Send + Sync` (e.g. `Map<dyn Any + Send>`) to add those auto
+///   traits.
+///
+/// Cumulatively, there are thus six forms of map:
+///
+/// - <code>[Map]&lt;dyn [std::any::Any]&gt;</code>, also spelled [`AnyMap`] for convenience.
+/// - <code>[Map]&lt;dyn [std::any::Any] + Send&gt;</code>
+/// - <code>[Map]&lt;dyn [std::any::Any] + Send + Sync&gt;</code>
+/// - <code>[Map]&lt;dyn [CloneAny]&gt;</code>
+/// - <code>[Map]&lt;dyn [CloneAny] + Send&gt;</code>
+/// - <code>[Map]&lt;dyn [CloneAny] + Send + Sync&gt;</code>
+///
+/// ## Example
+///
+/// (Here using the [`AnyMap`] convenience alias; the first line could use
+/// <code>[anymap::Map][Map]::&lt;[std::any::Any]&gt;::new()</code> instead if desired.)
 ///
 /// ```rust
-/// # use anymap::AnyMap;
-/// let mut data = AnyMap::new();
+/// let mut data = anymap::AnyMap::new();
 /// assert_eq!(data.get(), None::<&i32>);
 /// data.insert(42i32);
 /// assert_eq!(data.get(), Some(&42i32));
@@ -134,7 +152,7 @@ impl<A: ?Sized + UncheckedAnyExt> Clone for Map<A> where Box<A>: Clone {
     }
 }
 
-/// The most common type of `Map`: just using `Any`.
+/// The most common type of `Map`: just using `Any`; <code>[Map]&lt;dyn [Any]&gt;</code>.
 ///
 /// Why is this a separate type alias rather than a default value for `Map<A>`? `Map::new()`
 /// doesn’t seem to be happy to infer that it should go with the default value.
@@ -311,8 +329,7 @@ impl<'a, A: ?Sized + UncheckedAnyExt, V: IntoBox<A>> VacantEntry<'a, A, V> {
 
 #[cfg(test)]
 mod tests {
-    use {Map, AnyMap, Entry};
-    use any::{Any, CloneAny};
+    use super::*;
 
     #[derive(Clone, Debug, PartialEq)] struct A(i32);
     #[derive(Clone, Debug, PartialEq)] struct B(i32);
@@ -430,23 +447,18 @@ mod tests {
         fn assert_debug<T: ::std::fmt::Debug>() { }
         assert_send::<Map<dyn Any + Send>>();
         assert_send::<Map<dyn Any + Send + Sync>>();
-        assert_sync::<Map<dyn Any + Sync>>();
         assert_sync::<Map<dyn Any + Send + Sync>>();
         assert_debug::<Map<dyn Any>>();
         assert_debug::<Map<dyn Any + Send>>();
-        assert_debug::<Map<dyn Any + Sync>>();
         assert_debug::<Map<dyn Any + Send + Sync>>();
         assert_send::<Map<dyn CloneAny + Send>>();
         assert_send::<Map<dyn CloneAny + Send + Sync>>();
-        assert_sync::<Map<dyn CloneAny + Sync>>();
         assert_sync::<Map<dyn CloneAny + Send + Sync>>();
         assert_clone::<Map<dyn CloneAny + Send>>();
         assert_clone::<Map<dyn CloneAny + Send + Sync>>();
-        assert_clone::<Map<dyn CloneAny + Sync>>();
         assert_clone::<Map<dyn CloneAny + Send + Sync>>();
         assert_debug::<Map<dyn CloneAny>>();
         assert_debug::<Map<dyn CloneAny + Send>>();
-        assert_debug::<Map<dyn CloneAny + Sync>>();
         assert_debug::<Map<dyn CloneAny + Send + Sync>>();
     }
 }