rollup merge of #19932: elszben/master

First attempt to contribute to rust (and using github). This commit adds a few examples to std::io::TempDir. The examples seem to look okay (in my browser) and make check also passes.

src/libstd/io/tempfile.rs

@@ -23,6 +23,56 @@ use sync::atomic;
 
 /// A wrapper for a path to temporary directory implementing automatic
 /// scope-based deletion.
+///
+/// # Examples
+///
+/// ```no_run
+/// use std::io::TempDir;
+///
+/// {
+///     // create a temporary directory
+///     let tmpdir = match TempDir::new("mysuffix") {
+///         Ok(dir) => dir,
+///         Err(e) => panic!("couldn't create temporary directory: {}", e)
+///     };
+///
+///     // get the path of the temporary directory without affecting the wrapper
+///     let tmppath = tmpdir.path();
+///
+///     println!("The path of temporary directory is {}", tmppath.display());
+///
+///     // the temporary directory is automatically removed when tmpdir goes
+///     // out of scope at the end of the block
+/// }
+/// {
+///     // create a temporary directory, this time using a custom path
+///     let tmpdir = match TempDir::new_in(&Path::new("/tmp/best/custom/path"), "mysuffix") {
+///         Ok(dir) => dir,
+///         Err(e) => panic!("couldn't create temporary directory: {}", e)
+///     };
+///
+///     // get the path of the temporary directory and disable automatic deletion in the wrapper
+///     let tmppath = tmpdir.into_inner();
+///
+///     println!("The path of the not-so-temporary directory is {}", tmppath.display());
+///
+///     // the temporary directory is not removed here
+///     // because the directory is detached from the wrapper
+/// }
+/// {
+///     // create a temporary directory
+///     let tmpdir = match TempDir::new("mysuffix") {
+///         Ok(dir) => dir,
+///         Err(e) => panic!("couldn't create temporary directory: {}", e)
+///     };
+///
+///     // close the temporary directory manually and check the result
+///     match tmpdir.close() {
+///         Ok(_) => println!("success!"),
+///         Err(e) => panic!("couldn't remove temporary directory: {}", e)
+///     };
+/// }
+/// ```
 pub struct TempDir {
     path: Option<Path>,
     disarmed: bool