Document TrustedLen’s contract

Author: bluss

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 {}