Rollup merge of #66583 - Phlosioneer:patch-2, r=Dylan-DPC

Clarify Step Documentation

While the redesign is in progress (#62886), clarify the purpose of replace_zero and replace_one.

First, "returning itself" is technically impossible due to the function signature of &mut self -> Self. A clone or copy operation must be used. So this is now explicitly stated in the documentation.

Second, the added docs give some guidance about the actual contract around implementation of replace_zero and replace one. Specifically, the only usage is to create a range with no more steps, by setting start to replace_one and end to replace_zero. So the only property that is actually used is `replace_one > replace_zero`. See https://github.com/rust-lang/rust/issues/42168#issuecomment-489554232

The new documentation does not say that is the *only* contract, and so it should not be considered an api change. It just highlights the most important detail for implementors.

The redesign doesn't seem to be landing any time soon, so this is a stopgap measure to reduce confusion in the meantime.

1 files changed, 6 insertions, 2 deletions

diff --git a/src/libcore/iter/range.rs b/src/libcore/iter/range.rs
index efda3b263cc..63036f516a0 100644
--- a/src/libcore/iter/range.rs
+++ b/src/libcore/iter/range.rs
@@ -20,10 +20,14 @@ pub trait Step: Clone + PartialOrd + Sized {
     /// without overflow.
     fn steps_between(start: &Self, end: &Self) -> Option<usize>;
 
-    /// Replaces this step with `1`, returning itself.
+    /// Replaces this step with `1`, returning a clone of itself.
+    ///
+    /// The output of this method should always be greater than the output of replace_zero.
     fn replace_one(&mut self) -> Self;
 
-    /// Replaces this step with `0`, returning itself.
+    /// Replaces this step with `0`, returning a clone of itself.
+    ///
+    /// The output of this method should always be less than the output of replace_one.
     fn replace_zero(&mut self) -> Self;
 
     /// Adds one to this step, returning the result.