diff --git a/guide/src/class/protocols.md b/guide/src/class/protocols.md
index 3f3cc769f3d..51df95b4097 100644
--- a/guide/src/class/protocols.md
+++ b/guide/src/class/protocols.md
@@ -409,6 +409,6 @@ impl ClassWithGCSupport {
 
 > Note: these methods are part of the C API, PyPy does not necessarily honor them. If you are building for PyPy you should measure memory consumption to make sure you do not have runaway memory growth. See [this issue on the PyPy bug tracker](https://foss.heptapod.net/pypy/pypy/-/issues/3899).
 
-[`IterNextOutput`]: {{#PYO3_DOCS_URL}}/pyo3/class/iter/enum.IterNextOutput.html
+[`IterNextOutput`]: {{#PYO3_DOCS_URL}}/pyo3/pyclass/enum.IterNextOutput.html
 [`PySequence`]: {{#PYO3_DOCS_URL}}/pyo3/types/struct.PySequence.html
 [`CompareOp::matches`]: {{#PYO3_DOCS_URL}}/pyo3/pyclass/enum.CompareOp.html#method.matches
diff --git a/src/pyclass.rs b/src/pyclass.rs
index 028f3591ed4..432f45a1c71 100644
--- a/src/pyclass.rs
+++ b/src/pyclass.rs
@@ -90,7 +90,40 @@ impl CompareOp {
 /// Output of `__next__` which can either `yield` the next value in the iteration, or
 /// `return` a value to raise `StopIteration` in Python.
 ///
-/// See [`PyIterProtocol`](trait.PyIterProtocol.html) for an example.
+/// Usage example:
+///
+/// ```rust
+/// use pyo3::prelude::*;
+/// use pyo3::iter::IterNextOutput;
+///
+/// #[pyclass]
+/// struct PyClassIter {
+///     count: usize,
+/// }
+///
+/// #[pymethods]
+/// impl PyClassIter {
+///     #[new]
+///     pub fn new() -> Self {
+///         PyClassIter { count: 0 }
+///     }
+///
+///     fn __next__(&mut self) -> IterNextOutput<usize, &'static str> {
+///         if self.count < 5 {
+///             self.count += 1;
+///             // Given an instance `counter`, First five `next(counter)` calls yield 1, 2, 3, 4, 5.
+///             IterNextOutput::Yield(self.count)
+///         } else {
+///             // At the sixth time, we get a `StopIteration` with `'Ended'`.
+///             //     try:
+///             //         next(counter)
+///             //     except StopIteration as e:
+///             //         assert e.value == 'Ended'
+///             IterNextOutput::Return("Ended")
+///         }
+///     }
+/// }
+/// ```
 pub enum IterNextOutput<T, U> {
     /// The value yielded by the iterator.
     Yield(T),