Good read. Too bad none of that made it into the documentation.

steveklabnik · on March 2, 2018

So, a lot of it is in the documentation, but if you don't know Rust, then you might not infer it. This kind of thing is tough, as you need to balance audiences. The API docs assume you already know Rust.

For example:

Point 1 is known because the Item type is &str.

Point 2 is known because, well, that's the norm, but beyond that, SplitWhitespace is parameterized over a lifetime

Point 3 is known because it's an iterator; next() is its primary interface, which returns things one by one.

Point 4 is the "impl<'a> Iterator" bit

Point 5 is known because the return type of split_whitespace is this iterator, not Box<Iterator>

Point 6 is related.

If we repeated all of this stuff in every single bit of docs, it might make it more useful for some audiences, but also kinda destroy the docs for intermediate/advanced Rust users.

I'd love to make docs generally more accessible, but I'm not aware of any great solutions to this particular problem.

frankmcsherry · on March 2, 2018

You could probably just have a link that directs the reader to HN and posts a pre-filled "I have barely read about Rust, and it all seems over-complicated and ill-designed; convince me" comment.