Merge pull request #256 from rjsberry/feature-flag-docs

Improve feature flag documentation

Author: cuviper

Cargo.toml

@@ -54,6 +54,7 @@ tag-name = "{{version}}"
 
 [package.metadata.docs.rs]
 features = ["arbitrary", "quickcheck", "serde", "rayon"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [workspace]
 members = ["test-nostd", "test-serde"]

RELEASES.md

@@ -28,6 +28,9 @@
 
   - The `hashbrown` dependency has been updated to version 0.13.
 
+  - The `serde_seq` module has been moved from the crate root to below the
+    `map` module.
+
 - 1.9.2
 
   - `IndexMap` and `IndexSet` both implement `arbitrary::Arbitrary<'_>` and

src/arbitrary.rs

@@ -1,4 +1,5 @@
 #[cfg(feature = "arbitrary")]
+#[cfg_attr(docsrs, doc(cfg(feature = "arbitrary")))]
 mod impl_arbitrary {
     use crate::{IndexMap, IndexSet};
     use arbitrary::{Arbitrary, Result, Unstructured};
@@ -35,6 +36,7 @@ mod impl_arbitrary {
 }
 
 #[cfg(feature = "quickcheck")]
+#[cfg_attr(docsrs, doc(cfg(feature = "quickcheck")))]
 mod impl_quickcheck {
     use crate::{IndexMap, IndexSet};
     use alloc::boxed::Box;

src/lib.rs

@@ -14,7 +14,7 @@
 //! [`IndexSet`]: set/struct.IndexSet.html
 //!
 //!
-//! ### Feature Highlights
+//! ### Highlights
 //!
 //! [`IndexMap`] and [`IndexSet`] are drop-in compatible with the std `HashMap`
 //! and `HashSet`, but they also have some features of note:
@@ -26,6 +26,34 @@
 //! - The [`MutableKeys`][map::MutableKeys] trait, which gives opt-in mutable
 //!   access to hash map keys.
 //!
+//! ### Feature Flags
+//!
+//! To reduce the amount of compiled code in the crate by default, certain
+//! features are gated behind [feature flags]. These allow you to opt in to (or
+//! out of) functionality. Below is a list of the features available in this
+//! crate.
+//!
+//! * `std`: Enables features which require the Rust standard library. For more
+//!   information see the section on [`no_std`].
+//! * `rayon`: Enables parallel iteration and other parallel methods.
+//! * `serde`: Adds implementations for [`Serialize`] and [`Deserialize`]
+//!   to [`IndexMap`] and [`IndexSet`]. Alternative implementations for
+//!   (de)serializing [`IndexMap`] as an ordered sequence are available in the
+//!   [`map::serde_seq`] module.
+//! * `arbitrary`: Adds implementations for the [`arbitrary::Arbitrary`] trait
+//!   to [`IndexMap`] and [`IndexSet`].
+//! * `quickcheck`: Adds implementations for the [`quickcheck::Arbitrary`] trait
+//!   to [`IndexMap`] and [`IndexSet`].
+//!
+//! _Note: only the `std` feature is enabled by default._
+//!
+//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
+//! [`no_std`]: #no-standard-library-targets
+//! [`Serialize`]: `::serde::Serialize`
+//! [`Deserialize`]: `::serde::Deserialize`
+//! [`arbitrary::Arbitrary`]: `::arbitrary::Arbitrary`
+//! [`quickcheck::Arbitrary`]: `::quickcheck::Arbitrary`
+//!
 //! ### Alternate Hashers
 //!
 //! [`IndexMap`] and [`IndexSet`] have a default hasher type `S = RandomState`,
@@ -76,6 +104,8 @@
 //!
 //! [def]: map/struct.IndexMap.html#impl-Default
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 extern crate alloc;
 
 #[cfg(feature = "std")]
@@ -90,9 +120,8 @@ mod macros;
 mod equivalent;
 mod mutable_keys;
 #[cfg(feature = "serde")]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
 mod serde;
-#[cfg(feature = "serde")]
-pub mod serde_seq;
 mod util;
 
 pub mod map;
@@ -101,6 +130,7 @@ pub mod set;
 // Placed after `map` and `set` so new `rayon` methods on the types
 // are documented after the "normal" methods.
 #[cfg(feature = "rayon")]
+#[cfg_attr(docsrs, doc(cfg(feature = "rayon")))]
 mod rayon;
 
 #[cfg(feature = "rustc-rayon")]
@@ -245,4 +275,5 @@ impl core::fmt::Display for TryReserveError {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 impl std::error::Error for TryReserveError {}

src/macros.rs

@@ -1,4 +1,5 @@
 #[cfg(feature = "std")]
+#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 #[macro_export]
 /// Create an `IndexMap` from a list of key-value pairs
 ///
@@ -35,6 +36,7 @@ macro_rules! indexmap {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 #[macro_export]
 /// Create an `IndexSet` from a list of values
 ///

src/map.rs

@@ -5,6 +5,10 @@ mod core;
 mod iter;
 mod slice;
 
+#[cfg(feature = "serde")]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
+pub mod serde_seq;
+
 #[cfg(test)]
 mod tests;
 
@@ -148,6 +152,7 @@ where
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 impl<K, V> IndexMap<K, V> {
     /// Create a new map. (Does not allocate.)
     #[inline]
@@ -1112,6 +1117,7 @@ where
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 impl<K, V, const N: usize> From<[(K, V); N]> for IndexMap<K, V, RandomState>
 where
     K: Hash + Eq,

src/serde_seq.rs renamed to src/map/serde_seq.rs

@@ -12,13 +12,11 @@
 //! # use serde_derive::{Deserialize, Serialize};
 //! #[derive(Deserialize, Serialize)]
 //! struct Data {
-//!     #[serde(with = "indexmap::serde_seq")]
+//!     #[serde(with = "indexmap::map::serde_seq")]
 //!     map: IndexMap<i32, u64>,
 //!     // ...
 //! }
 //! ```
-//!
-//! Requires crate feature `"serde"`
 
 use serde::de::{Deserialize, Deserializer, SeqAccess, Visitor};
 use serde::ser::{Serialize, Serializer};
@@ -33,10 +31,8 @@ use crate::IndexMap;
 
 /// Serializes a `map::Slice` as an ordered sequence.
 ///
-/// This behaves like [`crate::serde_seq`] for `IndexMap`, serializing a sequence
+/// This behaves like [`crate::map::serde_seq`] for `IndexMap`, serializing a sequence
 /// of `(key, value)` pairs, rather than as a map that might not preserve order.
-///
-/// Requires crate feature `"serde"`
 impl<K, V> Serialize for MapSlice<K, V>
 where
     K: Serialize,
@@ -51,8 +47,6 @@ where
 }
 
 /// Serializes a `set::Slice` as an ordered sequence.
-///
-/// Requires crate feature `"serde"`
 impl<T> Serialize for SetSlice<T>
 where
     T: Serialize,
@@ -74,13 +68,11 @@ where
 /// # use serde_derive::Serialize;
 /// #[derive(Serialize)]
 /// struct Data {
-///     #[serde(serialize_with = "indexmap::serde_seq::serialize")]
+///     #[serde(serialize_with = "indexmap::map::serde_seq::serialize")]
 ///     map: IndexMap<i32, u64>,
 ///     // ...
 /// }
 /// ```
-///
-/// Requires crate feature `"serde"`
 pub fn serialize<K, V, S, T>(map: &IndexMap<K, V, S>, serializer: T) -> Result<T::Ok, T::Error>
 where
     K: Serialize + Hash + Eq,
@@ -130,13 +122,11 @@ where
 /// # use serde_derive::Deserialize;
 /// #[derive(Deserialize)]
 /// struct Data {
-///     #[serde(deserialize_with = "indexmap::serde_seq::deserialize")]
+///     #[serde(deserialize_with = "indexmap::map::serde_seq::deserialize")]
 ///     map: IndexMap<i32, u64>,
 ///     // ...
 /// }
 /// ```
-///
-/// Requires crate feature `"serde"`
 pub fn deserialize<'de, D, K, V, S>(deserializer: D) -> Result<IndexMap<K, V, S>, D::Error>
 where
     D: Deserializer<'de>,

src/rayon/map.rs

@@ -2,8 +2,6 @@
 //!
 //! You will rarely need to interact with this module directly unless you need to name one of the
 //! iterator types.
-//!
-//! Requires crate feature `"rayon"`
 
 use super::collect;
 use rayon::iter::plumbing::{Consumer, ProducerCallback, UnindexedConsumer};
@@ -21,7 +19,6 @@ use crate::Bucket;
 use crate::Entries;
 use crate::IndexMap;
 
-/// Requires crate feature `"rayon"`.
 impl<K, V, S> IntoParallelIterator for IndexMap<K, V, S>
 where
     K: Send,
@@ -37,7 +34,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<K, V> IntoParallelIterator for Box<Slice<K, V>>
 where
     K: Send,
@@ -81,7 +77,6 @@ impl<K: Send, V: Send> IndexedParallelIterator for IntoParIter<K, V> {
     indexed_parallel_iterator_methods!(Bucket::key_value);
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, K, V, S> IntoParallelIterator for &'a IndexMap<K, V, S>
 where
     K: Sync,
@@ -97,7 +92,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, K, V> IntoParallelIterator for &'a Slice<K, V>
 where
     K: Sync,
@@ -147,7 +141,6 @@ impl<K: Sync, V: Sync> IndexedParallelIterator for ParIter<'_, K, V> {
     indexed_parallel_iterator_methods!(Bucket::refs);
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, K, V, S> IntoParallelIterator for &'a mut IndexMap<K, V, S>
 where
     K: Sync + Send,
@@ -163,7 +156,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, K, V> IntoParallelIterator for &'a mut Slice<K, V>
 where
     K: Sync + Send,
@@ -207,7 +199,6 @@ impl<K: Sync + Send, V: Send> IndexedParallelIterator for ParIterMut<'_, K, V> {
     indexed_parallel_iterator_methods!(Bucket::ref_mut);
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, K, V, S> ParallelDrainRange<usize> for &'a mut IndexMap<K, V, S>
 where
     K: Send,
@@ -395,7 +386,6 @@ impl<K: Sync, V: Sync> IndexedParallelIterator for ParValues<'_, K, V> {
     indexed_parallel_iterator_methods!(Bucket::value_ref);
 }
 
-/// Requires crate feature `"rayon"`.
 impl<K, V, S> IndexMap<K, V, S>
 where
     K: Send,
@@ -412,7 +402,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<K, V> Slice<K, V>
 where
     K: Send,
@@ -546,7 +535,6 @@ impl<K: Send, V: Send> IndexedParallelIterator for ParValuesMut<'_, K, V> {
     indexed_parallel_iterator_methods!(Bucket::value_mut);
 }
 
-/// Requires crate feature `"rayon"`.
 impl<K, V, S> FromParallelIterator<(K, V)> for IndexMap<K, V, S>
 where
     K: Eq + Hash + Send,
@@ -567,7 +555,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<K, V, S> ParallelExtend<(K, V)> for IndexMap<K, V, S>
 where
     K: Eq + Hash + Send,
@@ -584,7 +571,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, K: 'a, V: 'a, S> ParallelExtend<(&'a K, &'a V)> for IndexMap<K, V, S>
 where
     K: Copy + Eq + Hash + Send + Sync,

src/rayon/set.rs

@@ -2,8 +2,6 @@
 //!
 //! You will rarely need to interact with this module directly unless you need to name one of the
 //! iterator types.
-//!
-//! Requires crate feature `"rayon"`.
 
 use super::collect;
 use rayon::iter::plumbing::{Consumer, ProducerCallback, UnindexedConsumer};
@@ -22,7 +20,6 @@ use crate::IndexSet;
 
 type Bucket<T> = crate::Bucket<T, ()>;
 
-/// Requires crate feature `"rayon"`.
 impl<T, S> IntoParallelIterator for IndexSet<T, S>
 where
     T: Send,
@@ -37,7 +34,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<T> IntoParallelIterator for Box<Slice<T>>
 where
     T: Send,
@@ -80,7 +76,6 @@ impl<T: Send> IndexedParallelIterator for IntoParIter<T> {
     indexed_parallel_iterator_methods!(Bucket::key);
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, T, S> IntoParallelIterator for &'a IndexSet<T, S>
 where
     T: Sync,
@@ -95,7 +90,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, T> IntoParallelIterator for &'a Slice<T>
 where
     T: Sync,
@@ -144,7 +138,6 @@ impl<T: Sync> IndexedParallelIterator for ParIter<'_, T> {
     indexed_parallel_iterator_methods!(Bucket::key_ref);
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, T, S> ParallelDrainRange<usize> for &'a mut IndexSet<T, S>
 where
     T: Send,
@@ -585,7 +578,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<T, S> FromParallelIterator<T> for IndexSet<T, S>
 where
     T: Eq + Hash + Send,
@@ -605,7 +597,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<T, S> ParallelExtend<T> for IndexSet<T, S>
 where
     T: Eq + Hash + Send,
@@ -621,7 +612,6 @@ where
     }
 }
 
-/// Requires crate feature `"rayon"`.
 impl<'a, T: 'a, S> ParallelExtend<&'a T> for IndexSet<T, S>
 where
     T: Copy + Eq + Hash + Send + Sync,