RangeFrom::step_by docs: fix example

[SimonSapin]

The previous example did not do what its description said. In it panicked on integer overflow in debug mode, and went into an infinite loop in release mode (wrapping back to 0 after printing 254).

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @alexcrichton (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[ranma42]

The example is now much better, but I am afraid that the overflow behaviour is still not clear.
Should we state that overflow should be avoided by the caller?
"Creates an iterator starting at the same point, but stepping by the given amount at each iteration." does not really convey the information about what is going to happen (for example, it is not obvious whether the step addition is panicking/wrapping/saturating/checked/...).

Would this work?
"Creates an iterator starting at the same point, but stepping by the given amount at each iteration. Stepping beyond the maximum value that can be represented by A is undefined behaviour."

[SimonSapin]

I think discussion of overflow should go into the docs of RangeFrom (which is itself an iterator) rather than RangeFrom::step_by (which gives a "subset" of that iterator)

[ranma42]

Yes, that seems right

[alexcrichton]

Can the ignore tag also be removed from the example? I'm a little surprised we have an ignored code example...

[SimonSapin]

Done. It was probably ignored because it didn’t work :)

[alexcrichton]

@bors: r+ 6e87d781a6eb3dae7014968f60c4ec2b137a9fe4

[Manishearth]

http://buildbot.rust-lang.org/builders/auto-linux-64-nopt-t/builds/7783/steps/test/logs/stdio

failures:

---- iter::RangeFrom<A>::step_by_0 stdout ----
    <anon>:4:22: 4:29 error: use of unstable library feature 'step_by': recent addition (see issue #27741)
<anon>:4     for i in (0u8..).step_by(2).take(10) {
                              ^~~~~~~
<anon>:4:22: 4:29 help: add #![feature(step_by)] to the crate attributes to enable
error: aborting due to previous error
thread 'iter::RangeFrom<A>::step_by_0' panicked at 'Box<Any>', ../src/libsyntax/errors/mod.rs:527

protip: run rustdoc --test on the file directly to avoid recompiling everything to run a doctest

[bors]

⌛ Testing commit 6e87d78 with merge 85ecc8b...

[Manishearth]

@bors r- force

(doctest not yet fixed)

[bors]

⛄ The build was interrupted to prioritize another pull request.

[SimonSapin]

Fixed and tested locally with rustdoc. This is a good tip, thanks Manish! So far I had made this PR in GitHub’s web editor, hoping it would be trivial…

[Manishearth]

@bors r=sfackler

[bors]

📌 Commit 70d4f26 has been approved by sfackler

[Manishearth]

Great! I'll stick it in a rollup since the build for the other PR just started anyway.