Change:
From : It's easy, according to implement my own ` implementation for free. In retrospect it makes sense, but it was not obvious to me at all just from reading the docs. It is not mentioned in , or the docs for . And as the link in my post suggests, trying to work my way around the ownership of the APIs led me quite far afield. Admittedly it's not the most common case, but I think it would save others time if the standard library at least mentioned this somewhere. EDIT: fixed forum link which changed its name when I marked it solved.
A section about "you should consider overloading these things" definitely sounds good. should also be on that list. (In the future or in nightly is in that list too, .)
Your forum link is broken.
The docs do say However, I do like 's suggestion, about talking about which methods you may want to override.
Such hints should be non-normative though to allow the implementations, especially specializations, to use different approaches in the future.
Agreed, I was picturing more which methods to consider overloading, not specifically which things use them. (Or, contrapositively, which things there's usually no reason to overload, like , because the default implementation is generally as good as it gets because it's a trivial wrapper.)
So basically this issue is about adding some documentation on which methods you might want to override right? Which methods do you think are best to mention? Or did I misinterpret the discussion?
That's correctly, probably under or near For now my inclination would be to mention and -- once stable it should be instead, but IIRC we don't mention unstable in the broader docs until it stabilizes.
What about adding this line of text at the end of the "Implementing Iterator" section? which call internally. However, it is also possible to write a custom implementation of methods such as and if an iterator is able to compute them more efficiently without calling . Feel free to adjust the text or make something up yourself :) If you agree I will create a PR for this.
I think it would also be nice to add something to the documentation. How about this? Rather than overriding this method directly, instead override the method.
in case it wasn't clear or you are not watching your GitHub notifications, I approve of both your and suggestions. I look forward to the PR!
Sorry for the late reply! I apparently don't get notifications for thumbs ups and the like! I will hopefully be able to create a PR somewhere this midday.

Discussion:
//! call `next()` on your iterator, until it reaches `None`. Let's go over that //! next. //! <ins> //! Also note that `Iterator` provides a default implementation of methods such as `nth` and `fold` //! which call `next` internally. However, it is also possible to write a custom implementation of //! methods like `nth` and `fold` if an iterator can compute them more efficiently without calling //! `next`. //! </ins> //! # for Loops and IntoIterator //! //! Rust's `for` loop syntax is actually sugar for iterators. Here's a basic

/// Creates an iterator that skips the first `n` elements. /// /// After they have been consumed, the rest of the elements are yielded. <ins> /// Rather than overriding this method directly, instead override the `nth` method. </ins> /// /// # Examples ///