Improve documentation of `needless_range_loop`

[flip1995]

I still believe this lint has grown too large, if we look at the doc page, it says "Checks for looping over the range of 0..len of some collection just to get the values by index", so at least the documentation should be updated to discuss any a..b range.

Originally posted by @ChrisJefferson in #6075 (comment)

We should improve the documentation of the needless_range_loop lint to better explain what cases this lint triggers on. Also make more clear, that using iterators usually has better performance (re-classify?).

[camsteffen]

Also make more clear, that using iterators usually has better performance (re-classify?).

I think it depends on what "usually" means. Of course we can't get an exact figure, but perhaps it can be shown that not improving perf is a highly unusual scenario. And in that case it should be perf.

[flip1995]

See #6930 and #6075 for some benchmarks. You almost always get better results with iterators, since you get rid of bounds checking.

[Skirmisher]

As someone who hasn't had much experience with Rust iterators yet, clippy's suggestion here confused me:

warning: the loop variable `count` is used to index `buf`
  --> src/hapi/reader.rs:63:17
   |
63 |             for count in 0..bytes_count {
   |                          ^^^^^^^^^^^^^^
   |
   = note: `#[warn(clippy::needless_range_loop)]` on by default
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#needless_range_loop
help: consider using an iterator
   |
63 |             for (count, <item>) in buf.iter_mut().enumerate().take(bytes_count) {
   |  

It was unclear to me where the tuple in this example was coming from. clippy was suggesting the correct thing (since count was not only used to index the buffer), but neither clippy nor the documentation explained how enumerate was the critical component, leaving me at a loss until I asked someone else about it. (Additionally, clippy didn't make explicit that <item> should be mut in this case, but that may be less important.)

[camsteffen]

Good point. We could change the help message to "consider using enumerate".

[tylerjw]

@rustbot claim

[tylerjw]

I submitted a tiny PR to address the concerns about the docs. Let me know if you think it satisfies the concerns in this issue.