Document TrustedLen’s contract

diff --git a/src/libcore/iter/traits.rs b/src/libcore/iter/traits.rs
index da150f1d57a63971a18d90c2ab41554b8896bcb2..a56a864f6180d4c26e4d59fad6674af4647ba42b 100644 (file)
--- a/src/libcore/iter/traits.rs
+++ b/src/libcore/iter/traits.rs
@@ -666,7 +666,19 @@ pub trait FusedIterator: Iterator {}
 #[unstable(feature = "fused", issue = "35602")]
 impl<'a, I: FusedIterator + ?Sized> FusedIterator for &'a mut I {}
 
-/// An iterator that has correct length
+/// An iterator that reports an accurate length using size_hint.
+///
+/// The iterator reports a size hint where it is either exact
+/// (lower bound is equal to upper bound), or the upper bound is `None`.
+/// The upper bound must only be `None` if the actual iterator length is
+/// larger than `usize::MAX`.
+///
+/// The iterator must produce exactly the number of elements it reported.
+///
+/// # Safety
+///
+/// This trait must only be implemented when the contract is upheld.
+/// Consumers of this trait must inspect `.size_hint()`’s upper bound.
 #[unstable(feature = "trusted_len", issue = "0")]
 pub unsafe trait TrustedLen : Iterator {}