Standardize on self-containedness of examples in docs.

[steveklabnik]

Issue by huonw
Sunday Sep 22, 2013 at 07:49 GMT

For earlier discussion, see rust-lang/rust#9403

This issue was labelled with: A-docs, B-RFC in the Rust repository

---

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).

[Centril]

I believe https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md sufficiently deals with this.