Standardize on self-containedness of examples in docs.

[huonw]

There are many examples in the docs that require some adjustments to get to compile, e.g. the following requires a main function:

let a = [0];
let b = [1];
let mut it = a.iter().chain(b.iter());
assert_eq!(it.next().get(), &0);
assert_eq!(it.next().get(), &1);
assert!(it.next().is_none());

(Iterator.chain at the time of filing.)

And others that are entirely self-contained, and can just be copy-pasted to be run.

use std::rand;

fn main () {
    let tuple_ptr = rand::random::<~(f64, char)>();
    printfln!(tuple_ptr)
}

(One of the examples at the top of std::rand.)

It seems like it would be good to be consistent about this. I prefer the latter, and it would make automatically running the tests much easier (#2925).

[alexcrichton]

I would actually put my vote in for the first because otherwise we'd have to duplicate the same fn main() + tabbing logic to all examples when it's not really entirely necessary. It's true that you can't just copy/paste code at that point, but I personally think of documentation as examples moreso than standalong programs.

[bluss]

This is really a tangent, but I note that the chain example would not compile (uses get instead of unwrap), yet it is written with assertions so that a test runner can run it well, but it's a pretty hard to read example for a human reader of documentation! We should find a standard for how to present "prints this" and "now has this value" in these examples.

[bluss]

It would be a bad pattern if we had to repeat the name of the module (and even the name of the crate) in each example.

[emberian]

I prefer the first. I'd prefer to have some sort of header or standard template that can be modified, that doesn't show up in docs. Docs are primarily for showing how to do something simply. Something like how rusti-the-bot works would be nice.

[pythonesque]

I think there are some types of examples (cross-crate, etc.) that would be very hard to get working inline at all, as we've seen with rusti. We would also be unable to assert that, e.g., particular output happened with a convention-based approach. I think a good option might be to maintain the examples as sets of tests, which can be required to pass or fail as needed. Any code that is supposed to show up in the example would need to be wrapped in a block of some sort with metadata specifying that it was an example. We could then use our existing test infrastructure to parse the examples (which could do anything our tests could do) and, if they passed, import the examples. The only downside I can think of is that the examples wouldn't be inline with where they showed up (initially, I mean, not in the final result), but I think that's probably unavoidable to some extent for examples that span multiple files.

[steveklabnik]

I think that the answer is 'link to the playground with a full example'.

[emberian]

I agree.

[steveklabnik]

I'm pulling a massive triage effort to get us ready for 1.0. As part of this, I'm moving stuff that's wishlist-like to the RFCs repo, as that's where major new things should get discussed/prioritized.

This issue has been moved to the RFCs repo: rust-lang/rfcs#688