Little/No documentation around the "timeout" arg to stream-building functions

[JustAnotherCodemonkey]

The problem

The documentation is very vague around what exactly it does. The only real mention of it and hint at what it does is "None=blocking, Some(Duration)=timeout" in an example code snippet in the crate root. "None=blocking" what is being blocked here? Not the stream builder fn calling thread; the docs make it very clear that never happens. "Some(Duration)=timeout" is not helpful at all; 'passing a Some(_) to "timeout" means there is a timeout' is self-evident unlike what's being timed, when it's being timed, and what happens when the timer runs out.

Additionally, although there are 2 examples of None being passed to this argument, there are no examples of a Some being passed. This would be fine if there were documentation to explain what the timeout was, what it did, why it wasn't being used here, and just as importantly, when it would be used.

If there is more descriptive documentation somewhere, the fact that I couldn't find it is, itself, a problem. There should be more of a mention in the explanations of the example code containing build_output_stream.

Potential solutions

I'm not saying of course that literally every argument to every function needs to be documented as the crate does an excellent job of explaining much in few words and most things are either demonstrated in the example code or are self-evident. It's just that at least this falls through the cracks of not being self-evident.

I think that that comment in the example code is a good idea. A short explanation of what None and Some do there is definitely called for and it would definitely be nice to have some sort of mention of why one might want to use a timeout in the description of how data callbacks work under the build_output_stream example in the crate docs.