Clarify documentation of choose_weighted(_mut) mentioning accurate behavior with floats (#1245)

* Fix the documentation for `choose_weighted(_mut)` as discussed in #1243.

* Mention that elements of zero weight are handled as expected by `WeightedIndex` as discussed in #1243.

Additionally fix some minor issues.

* Let the second example of `WeightedIndex` use floats to stress that they are handled correctly for the zero case.

* Manually indent doc comments.

Author: ISibboI

src/distributions/weighted_index.rs

@@ -25,8 +25,10 @@ use serde::{Serialize, Deserialize};
 /// Sampling a `WeightedIndex` distribution returns the index of a randomly
 /// selected element from the iterator used when the `WeightedIndex` was
 /// created. The chance of a given element being picked is proportional to the
-/// value of the element. The weights can use any type `X` for which an
-/// implementation of [`Uniform<X>`] exists.
+/// weight of the element. The weights can use any type `X` for which an
+/// implementation of [`Uniform<X>`] exists. The implementation guarantees that
+/// elements with zero weight are never picked, even when the weights are
+/// floating point numbers.
 ///
 /// # Performance
 ///
@@ -42,8 +44,8 @@ use serde::{Serialize, Deserialize};
 /// weights of type `X`, where `N` is the number of weights. However, since
 /// `Vec` doesn't guarantee a particular growth strategy, additional memory
 /// might be allocated but not used. Since the `WeightedIndex` object also
-/// contains, this might cause additional allocations, though for primitive
-/// types, [`Uniform<X>`] doesn't allocate any memory.
+/// contains an instance of `X::Sampler`, this might cause additional allocations,
+/// though for primitive types, [`Uniform<X>`] doesn't allocate any memory.
 ///
 /// Sampling from `WeightedIndex` will result in a single call to
 /// `Uniform<X>::sample` (method of the [`Distribution`] trait), which typically
@@ -65,7 +67,7 @@ use serde::{Serialize, Deserialize};
 ///     println!("{}", choices[dist.sample(&mut rng)]);
 /// }
 ///
-/// let items = [('a', 0), ('b', 3), ('c', 7)];
+/// let items = [('a', 0.0), ('b', 3.0), ('c', 7.0)];
 /// let dist2 = WeightedIndex::new(items.iter().map(|item| item.1)).unwrap();
 /// for _ in 0..100 {
 ///     // 0% chance to print 'a', 30% chance to print 'b', 70% chance to print 'c'

src/seq/mod.rs

@@ -123,21 +123,25 @@ pub trait SliceRandom {
     /// therefore `weight(x) / s`, where `s` is the sum of all `weight(x)`.
     ///
     /// For slices of length `n`, complexity is `O(n)`.
-    /// See also [`choose_weighted_mut`], [`distributions::weighted`].
+    /// For more information about the underlying algorithm,
+    /// see [`distributions::WeightedIndex`].
+    ///
+    /// See also [`choose_weighted_mut`].
     ///
     /// # Example
     ///
     /// ```
     /// use rand::prelude::*;
     ///
-    /// let choices = [('a', 2), ('b', 1), ('c', 1)];
+    /// let choices = [('a', 2), ('b', 1), ('c', 1), ('d', 0)];
     /// let mut rng = thread_rng();
-    /// // 50% chance to print 'a', 25% chance to print 'b', 25% chance to print 'c'
+    /// // 50% chance to print 'a', 25% chance to print 'b', 25% chance to print 'c',
+    /// // and 'd' will never be printed
     /// println!("{:?}", choices.choose_weighted(&mut rng, |item| item.1).unwrap().0);
     /// ```
     /// [`choose`]: SliceRandom::choose
     /// [`choose_weighted_mut`]: SliceRandom::choose_weighted_mut
-    /// [`distributions::weighted`]: crate::distributions::weighted
+    /// [`distributions::WeightedIndex`]: crate::distributions::WeightedIndex
     #[cfg(feature = "alloc")]
     #[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
     fn choose_weighted<R, F, B, X>(
@@ -161,11 +165,14 @@ pub trait SliceRandom {
     /// therefore `weight(x) / s`, where `s` is the sum of all `weight(x)`.
     ///
     /// For slices of length `n`, complexity is `O(n)`.
-    /// See also [`choose_weighted`], [`distributions::weighted`].
+    /// For more information about the underlying algorithm,
+    /// see [`distributions::WeightedIndex`].
+    ///
+    /// See also [`choose_weighted`].
     ///
     /// [`choose_mut`]: SliceRandom::choose_mut
     /// [`choose_weighted`]: SliceRandom::choose_weighted
-    /// [`distributions::weighted`]: crate::distributions::weighted
+    /// [`distributions::WeightedIndex`]: crate::distributions::WeightedIndex
     #[cfg(feature = "alloc")]
     #[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
     fn choose_weighted_mut<R, F, B, X>(