Document `Sum::sum` returns additive identities for `[]`

Because the neutral element of `<fNN as iter::Sum>` was changed to
`neg_zero`, the documentation needed to be updated, as it was reporting
inadequate information about what should be expected from the return.

Co-authored-by: Jubilee <workingjubilee@gmail.com>

1 files changed, 6 insertions, 1 deletions

diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs
index 91c3a4b29b5..42886e90f99 100644
--- a/library/core/src/iter/traits/iterator.rs
+++ b/library/core/src/iter/traits/iterator.rs
@@ -3493,7 +3493,8 @@ pub trait Iterator {
     ///
     /// Takes each element, adds them together, and returns the result.
     ///
-    /// An empty iterator returns the zero value of the type.
+    /// An empty iterator returns the *additive identity* ("zero") of the type,
+    /// which is `0` for integers and `-0.0` for floats.
     ///
     /// `sum()` can be used to sum any type implementing [`Sum`][`core::iter::Sum`],
     /// including [`Option`][`Option::sum`] and [`Result`][`Result::sum`].
@@ -3511,6 +3512,10 @@ pub trait Iterator {
     /// let sum: i32 = a.iter().sum();
     ///
     /// assert_eq!(sum, 6);
+    ///
+    /// let b: Vec<f32> = vec![];
+    /// let sum: f32 = b.iter().sum();
+    /// assert_eq!(sum, -0.0_f32);
     /// ```
     #[stable(feature = "iter_arith", since = "1.11.0")]
     fn sum<S>(self) -> S