I agree that the rust docs need work, but I disagree with your example. cycle is just a method defined as part of the Iterator implementation - it's just like a method you might define to implement an interface in Java. JavaDocs actually have the same layout as the Rust documentation in this case: you have to actually click on the method to find out how it works. This is also how docs for other languages are often laid out as well.