So I'm going through my contributions and adding code examples for most of the API stuff out there that isn't immediately obvious.

I only have one example of an existing code sample that is live in the libstd docs right now, and that's for net::tcp::listen. Suffice to say: it is very out-of-date with the current state of the art for rust. This is a sad discovery, on my part.

Since more literate code examples in the docs is probably a good thing, this is where I'm putting my energies for documentation of my work (as opposed to blog posts, emails to the list, etc). I'm trying to make the examples complete, illustrative and durable (the latter of which I have no control over).

Cutting to the chase:

I'd be happy with something like what (I'm told) we have in the tutorial markdown: have the build automation (rustdoc, in this case?) do a run-pass on all code blocks (by some known convention) that appear in docstrings, for the greater good.

Thoughts?