Merge pull request #11 from brson/next

Add lots of docs. Rust doc days!

Author: alexcrichton

src/lib.rs

@@ -13,6 +13,43 @@
        html_root_url = "https://doc.rust-lang.org/tempdir/")]
 #![cfg_attr(test, deny(warnings))]
 
+//! Temporary directories of files.
+//!
+//! The [`TempDir`] type creates a directory on the file system that
+//! is deleted once it goes out of scope. At construction, the
+//! `TempDir` creates a new directory with a randomly generated name
+//! and a prefix of your choosing.
+//!
+//! [`TempDir`]: struct.TempDir.html
+//! [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html
+//!
+//! # Examples
+//!
+//! ```
+//! extern crate tempdir;
+//!
+//! use std::fs::File;
+//! use std::io::Write;
+//! use tempdir::TempDir;
+//!
+//! fn main() {
+//!     // Create a directory inside of `std::env::temp_dir()`, named with
+//!     // the prefix "example".
+//!     let tmp_dir = TempDir::new("example").expect("create temp dir");
+//!     let file_path = tmp_dir.path().join("my-temporary-note.txt");
+//!     let mut tmp_file = File::create(file_path).expect("create temp file");
+//!     writeln!(tmp_file, "Brian was here. Briefly.").expect("write temp file");
+//!
+//!     // By closing the `TempDir` explicitly, we can check that it has
+//!     // been deleted successfully. If we don't close it explicitly,
+//!     // the directory will still be deleted when `tmp_dir` goes out
+//!     // of scope, but we won't know whether deleting the directory
+//!     // succeeded.
+//!     drop(tmp_file);
+//!     tmp_dir.close().expect("delete temp dir");
+//! }
+//! ```
+
 extern crate rand;
 
 use std::env;
@@ -22,8 +59,50 @@ use std::fs;
 use std::path::{self, PathBuf, Path};
 use rand::{thread_rng, Rng};
 
-/// A wrapper for a path to temporary directory implementing automatic
-/// scope-based deletion.
+/// A directory in the filesystem that is automatically deleted when
+/// it goes out of scope.
+///
+/// The [`TempDir`] type creates a directory on the file system that
+/// is deleted once it goes out of scope. At construction, the
+/// `TempDir` creates a new directory with a randomly generated name,
+/// and with a prefix of your choosing.
+///
+/// The default constructor, [`TempDir::new`], creates directories in
+/// the location returned by [`std::env::temp_dir()`], but `TempDir`
+/// can be configured to manage a temporary directory in any location
+/// by constructing with [`TempDir::new_in`].
+///
+/// After creating a `TempDir`, work with the file system by doing
+/// standard [`std::fs`] file system operations on its [`Path`],
+/// which can be retrieved with [`TempDir::path`]. Once the `TempDir`
+/// value is dropped, the directory at the path will be deleted, along
+/// with any files and directories it contains. It is your responsibility
+/// to ensure that no further file system operations are attempted
+/// inside the temporary directory once it has been deleted.
+///
+/// Various platform-specific conditions may cause `TempDir` to fail
+/// to delete the underlying directory. It's important to ensure that
+/// handles (like [`File`] and [`ReadDir`]) to files inside the
+/// directory are dropped before the `TempDir` goes out of scope. The
+/// `TempDir` destructor will silently ignore any errors in deleting
+/// the directory; to instead handle errors call [`TempDir::close`].
+///
+/// Note that if the program exits before the `TempDir` destructor is
+/// run, such as via [`std::process::exit`], by segfaulting, or by
+/// receiving a signal like `SIGINT`, then the temporary directory
+/// will not be deleted.
+/// 
+/// [`File`]: http://doc.rust-lang.org/std/fs/struct.File.html
+/// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
+/// [`ReadDir`]: http://doc.rust-lang.org/std/fs/struct.ReadDir.html
+/// [`TempDir::close`]: struct.TempDir.html#method.close
+/// [`TempDir::new`]: struct.TempDir.html#method.new
+/// [`TempDir::new_in`]: struct.TempDir.html#method.new_in
+/// [`TempDir::path`]: struct.TempDir.html#method.path
+/// [`TempDir`]: struct.TempDir.html
+/// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html
+/// [`std::fs`]: http://doc.rust-lang.org/std/fs/index.html
+/// [`std::process::exit`]: http://doc.rust-lang.org/std/process/fn.exit.html
 pub struct TempDir {
     path: Option<PathBuf>,
 }
@@ -38,11 +117,59 @@ const NUM_RETRIES: u32 = 1 << 31;
 const NUM_RAND_CHARS: usize = 12;
 
 impl TempDir {
-    /// Attempts to make a temporary directory inside of `tmpdir` whose name
-    /// will have the prefix `prefix`. The directory will be automatically
-    /// deleted once the returned wrapper is destroyed.
+    /// Attempts to make a temporary directory inside of `env::temp_dir()` whose
+    /// name will have the prefix, `prefix`. The directory and
+    /// everything inside it will be automatically deleted once the
+    /// returned `TempDir` is destroyed.
+    ///
+    /// # Errors
+    ///
+    /// If the directory can not be created, `Err` is returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::fs::File;
+    /// use std::io::Write;
+    /// use tempdir::TempDir;
+    ///
+    /// // Create a directory inside of `std::env::temp_dir()`, named with
+    /// // the prefix, "example".
+    /// let tmp_dir = TempDir::new("example").expect("create temp dir");
+    /// let file_path = tmp_dir.path().join("my-temporary-note.txt");
+    /// let mut tmp_file = File::create(file_path).expect("create temp file");
+    /// writeln!(tmp_file, "Brian was here. Briefly.").expect("write temp file");
+    ///
+    /// // `tmp_dir` goes out of scope, the directory as well as
+    /// // `tmp_file` will be deleted here.
+    /// ```
+    pub fn new(prefix: &str) -> io::Result<TempDir> {
+        TempDir::new_in(&env::temp_dir(), prefix)
+    }
+
+    /// Attempts to make a temporary directory inside of `tmpdir`
+    /// whose name will have the prefix `prefix`. The directory and
+    /// everything inside it will be automatically deleted once the
+    /// returned `TempDir` is destroyed.
     ///
-    /// If no directory can be created, `Err` is returned.
+    /// # Errors
+    ///
+    /// If the directory can not be created, `Err` is returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::fs::{self, File};
+    /// use std::io::Write;
+    /// use tempdir::TempDir;
+    ///
+    /// // Create a directory inside of the current directory, named with
+    /// // the prefix, "example".
+    /// let tmp_dir = TempDir::new_in(".", "example").expect("create temp dir");
+    /// let file_path = tmp_dir.path().join("my-temporary-note.txt");
+    /// let mut tmp_file = File::create(file_path).expect("create temp file");
+    /// writeln!(tmp_file, "Brian was here. Briefly.").expect("write temp file");
+    /// ```
     pub fn new_in<P: AsRef<Path>>(tmpdir: P, prefix: &str) -> io::Result<TempDir> {
         let storage;
         let mut tmpdir = tmpdir.as_ref();
@@ -76,32 +203,96 @@ impl TempDir {
                        "too many temporary directories already exist"))
     }
 
-    /// Attempts to make a temporary directory inside of `env::temp_dir()` whose
-    /// name will have the prefix `prefix`. The directory will be automatically
-    /// deleted once the returned wrapper is destroyed.
+    /// Accesses the [`Path`] to the temporary directory.
     ///
-    /// If no directory can be created, `Err` is returned.
-    pub fn new(prefix: &str) -> io::Result<TempDir> {
-        TempDir::new_in(&env::temp_dir(), prefix)
+    /// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tempdir::TempDir;
+    ///
+    /// let tmp_path;
+    ///
+    /// {
+    ///    let tmp_dir = TempDir::new("example").expect("create temp dir");
+    ///    tmp_path = tmp_dir.path().to_owned();
+    ///
+    ///    // Check that the temp directory actually exists.
+    ///    assert!(tmp_path.exists());
+    ///
+    ///    // End of `tmp_dir` scope, directory will be deleted
+    /// }
+    ///
+    /// // Temp directory should be deleted by now
+    /// assert_eq!(tmp_path.exists(), false);
+    /// ```
+    pub fn path(&self) -> &path::Path {
+        self.path.as_ref().unwrap()
     }
 
-    /// Unwrap the wrapped `std::path::Path` from the `TempDir` wrapper.
-    /// This discards the wrapper so that the automatic deletion of the
-    /// temporary directory is prevented.
+    /// Unwraps the [`Path`] contained in the `TempDir` and
+    /// returns it. This destroys the `TempDir` without deleting the
+    /// directory represented by the returned `Path`.
+    ///
+    /// [`Path`]: http://doc.rust-lang.org/std/path/struct.Path.html
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::fs;
+    /// use tempdir::TempDir;
+    ///
+    /// let tmp_dir = TempDir::new("example").expect("create temp dir");
+    ///
+    /// // Convert `tmp_dir` into a `Path`, destroying the `TempDir`
+    /// // without deleting the directory.
+    /// let tmp_path = tmp_dir.into_path();
+    ///
+    /// // Delete the temporary directory ourselves.
+    /// fs::remove_dir_all(tmp_path).expect("remove temp dir");
+    /// ```
     pub fn into_path(mut self) -> PathBuf {
         self.path.take().unwrap()
     }
 
-    /// Access the wrapped `std::path::Path` to the temporary directory.
-    pub fn path(&self) -> &path::Path {
-        self.path.as_ref().unwrap()
-    }
-
-    /// Close and remove the temporary directory
+    /// Closes and removes the temporary directory, returing a `Result`.
     ///
     /// Although `TempDir` removes the directory on drop, in the destructor
     /// any errors are ignored. To detect errors cleaning up the temporary
     /// directory, call `close` instead.
+    ///
+    /// # Errors
+    ///
+    /// This function may return a variety of [`std::io::Error`]s that result from deleting
+    /// the files and directories contained with the temporary directory,
+    /// as well as from deleting the temporary directory itself. These errors
+    /// may be platform specific.
+    ///
+    /// [`std::io::Error`]: http://doc.rust-lang.org/std/io/struct.Error.html
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::fs::File;
+    /// use std::io::Write;
+    /// use tempdir::TempDir;
+    ///
+    /// // Create a directory inside of `std::env::temp_dir()`, named with
+    /// // the prefix, "example".
+    /// let tmp_dir = TempDir::new("example").expect("create temp dir");
+    /// let file_path = tmp_dir.path().join("my-temporary-note.txt");
+    /// let mut tmp_file = File::create(file_path).expect("create temp file");
+    /// writeln!(tmp_file, "Brian was here. Briefly.").expect("write temp file");
+    ///
+    /// // By closing the `TempDir` explicitly we can check that it has
+    /// // been deleted successfully. If we don't close it explicitly,
+    /// // the directory will still be deleted when `tmp_dir` goes out
+    /// // of scope, but we won't know whether deleting the directory
+    /// // succeeded.
+    /// drop(tmp_file);
+    /// tmp_dir.close().expect("delete temp dir");
+    /// ```
     pub fn close(mut self) -> io::Result<()> {
         self.cleanup_dir()
     }