doc: make it easier to pick the correct tempfile constructor/type

Author: Stebalien

src/dir/mod.rs

@@ -20,7 +20,7 @@ use crate::Builder;
 #[cfg(doc)]
 use crate::env;
 
-/// Create a new temporary directory.
+/// Create a new temporary directory. Also see [`tempdir_in`].
 ///
 /// The `tempdir` function creates a directory in the file system and returns a
 /// [`TempDir`]. The directory will be automatically deleted when the `TempDir`'s
@@ -67,7 +67,7 @@ pub fn tempdir() -> io::Result<TempDir> {
     TempDir::new()
 }
 
-/// Create a new temporary directory in a specific directory.
+/// Create a new temporary directory in a specific directory. Also see [`tempdir`].
 ///
 /// The `tempdir_in` function creates a directory in the specified directory
 /// and returns a [`TempDir`].

src/file/mod.rs

@@ -19,7 +19,7 @@ use crate::Builder;
 
 mod imp;
 
-/// Create a new temporary file.
+/// Create a new temporary file. Also see [`tempfile_in`].
 ///
 /// The file will be created in the location returned by [`env::temp_dir()`].
 ///
@@ -52,7 +52,7 @@ pub fn tempfile() -> io::Result<File> {
     tempfile_in(env::temp_dir())
 }
 
-/// Create a new temporary file in the specified directory.
+/// Create a new temporary file in the specified directory. Also see [`tempfile`].
 ///
 /// # Security
 ///

src/lib.rs

@@ -1,17 +1,20 @@
-//! Temporary files and directories.
+//! This is a library for creating temporary files and directories that are automatically deleted
+//! when no longer referenced (i.e., on drop).
 //!
-//! - Use the [`tempfile()`] function for temporary files
-//! - Use the [`tempdir()`] function for temporary directories.
+//! - Use [`tempfile()`] when you need a real [`std::fs::File`] but don't need to refer to it
+//!   by-path.
+//! - Use [`NamedTempFile::new()`] when you need a _named_ temporary file that can be refered to its
+//!   path.
+//! - Use [`tempdir()`] when you need a temporary directory that will be recursively deleted on drop.
+//! - Use [`spooled_tempfile()`] when you need an in-memory buffer that will ultimately be backed by
+//!   a temporary file if it gets too large.
 //!
 //! # Design
 //!
 //! This crate provides several approaches to creating temporary files and directories.
 //! [`tempfile()`] relies on the OS to remove the temporary file once the last handle is closed.
 //! [`TempDir`] and [`NamedTempFile`] both rely on Rust destructors for cleanup.
 //!
-//! When choosing between the temporary file variants, prefer `tempfile`
-//! unless you either need to know the file's path or to be able to persist it.
-//!
 //! ## Resource Leaking
 //!
 //! `tempfile` will (almost) never fail to cleanup temporary resources. However `TempDir` and

src/spooled.rs

@@ -22,13 +22,20 @@ pub struct SpooledTempFile {
     inner: SpooledData,
 }
 
-/// Create a new spooled temporary file.
+/// Create a new [`SpooledTempFile`]. Also see [`spooled_tempfile_in`].
 ///
 /// # Security
 ///
 /// This variant is secure/reliable in the presence of a pathological temporary
 /// file cleaner.
 ///
+/// # Backing Storage
+///
+/// By default, the underlying temporary file will be created in your operating system's temporary
+/// file directory which is _often_ an in-memory filesystem. You may want to consider using
+/// [`spooled_tempfile_in`] instead, passing a storage-backed filesystem (e.g., `/var/tmp` on
+/// Linux).
+///
 /// # Resource Leaking
 ///
 /// The temporary file will be automatically removed by the OS when the last
@@ -60,7 +67,7 @@ pub fn spooled_tempfile(max_size: usize) -> SpooledTempFile {
 
 /// Construct a new [`SpooledTempFile`], backed by a file in the specified directory. Use this when,
 /// e.g., you need the temporary file to be backed by a specific filesystem (e.g., when your default
-/// temporary directory is in-memory).
+/// temporary directory is in-memory). Also see [`spooled_tempfile`].
 ///
 /// **NOTE:** The specified path isn't checked until the temporary file is "rolled over" into a real
 /// temporary file. If the specified directory isn't writable, writes to the temporary file will