Rollup merge of #136710 - JakenHerman:jaken/iterator-docs, r=workingjubilee

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.

Relevant Commit: https://github.com/rust-lang/rust/commit/490818851860fb257e23fe7aa0ee32eaffc4ba40
Relevant Pull Request: https://github.com/rust-lang/rust/pull/129321

---

The referenced commit causes unintended side effects on presentation layer applications like using Tera templates, for example. I'm not sure what the motivation was behind the original change, but it seems like more discussion should be put into this issue and potentially have that change reverted.

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