Merge pull request #33 from epage/audit

docs: Quick and dirty audit

Author: epage

src/assert.rs

@@ -1,4 +1,6 @@
-//! `process::Output` assertions.
+//! [`Output`][Output] assertions.
+//!
+//! [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
 
 use std::fmt;
 use std::process;
@@ -10,7 +12,7 @@ use predicates::str::PredicateStrExt;
 use errors::dump_buffer;
 use errors::output_fmt;
 
-/// Assert the state of an `Output`.
+/// Assert the state of an [`Output`][Output].
 ///
 /// # Examples
 ///
@@ -24,8 +26,10 @@ use errors::output_fmt;
 ///     .assert()
 ///     .success();
 /// ```
+///
+/// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
 pub trait OutputAssertExt {
-    /// Wrap with an interface for that provides assertions on the `process::Output`.
+    /// Wrap with an interface for that provides assertions on the [`Output`][Output].
     ///
     /// # Examples
     ///
@@ -39,6 +43,8 @@ pub trait OutputAssertExt {
     ///     .assert()
     ///     .success();
     /// ```
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
     fn assert(self) -> Assert;
 }
 
@@ -55,9 +61,9 @@ impl<'c> OutputAssertExt for &'c mut process::Command {
     }
 }
 
-/// Assert the state of an `Output`.
+/// Assert the state of an [`Output`][Output].
 ///
-/// Create an `Assert` through the `OutputAssertExt` trait.
+/// Create an `Assert` through the [`OutputAssertExt`][OutputAssertExt] trait.
 ///
 /// # Examples
 ///
@@ -71,13 +77,18 @@ impl<'c> OutputAssertExt for &'c mut process::Command {
 ///     .assert()
 ///     .success();
 /// ```
+///
+/// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
+/// [OutputAssertExt]: trait.OutputAssertExt.html
 pub struct Assert {
     output: process::Output,
     context: Vec<(&'static str, Box<fmt::Display>)>,
 }
 
 impl Assert {
-    /// Create an `Assert` for a given `Output`.
+    /// Create an `Assert` for a given [`Output`][Output].
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
     pub fn new(output: process::Output) -> Self {
         Self {
             output,
@@ -94,7 +105,9 @@ impl Assert {
         self
     }
 
-    /// Access the contained `std::process::Output`.
+    /// Access the contained [`Output`][Output].
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
     pub fn get_output(&self) -> &process::Output {
         &self.output
     }
@@ -307,7 +320,8 @@ impl fmt::Debug for Assert {
     }
 }
 
-/// Used by `Assert::code` to convert `Self` into the needed `Predicate<i32>`.
+/// Used by [`Assert::code`][Assert_code] to convert `Self` into the needed
+/// [`Predicate<i32>`][Predicate].
 ///
 /// # Examples
 ///
@@ -328,6 +342,9 @@ impl fmt::Debug for Assert {
 ///     .assert()
 ///     .code(predicates::ord::eq(42));
 /// ```
+///
+/// [Assert_code]: struct.Assert.html#method.code
+/// [Predicate]: https://docs.rs/predicates/0.5.2/predicates/trait.Predicate.html
 pub trait IntoCodePredicate<P>
 where
     P: predicates::Predicate<i32>,
@@ -374,7 +391,12 @@ impl IntoCodePredicate<predicates::iter::InPredicate<i32>> for &'static [i32] {
     }
 }
 
-/// Used by `Assert` to convert Self into the needed `Predicate<[u8]>`.
+/// Used by [`Assert::stdout`][Assert_stdout] and [`Assert::stderr`][Assert_stderr] to convert Self
+/// into the needed [`Predicate<[u8]>`][Predicate].
+///
+/// [Assert_stdout]: struct.Assert.html#method.stdout
+/// [Assert_stderr]: struct.Assert.html#method.stderr
+/// [Predicate]: https://docs.rs/predicates/0.5.2/predicates/trait.Predicate.html
 pub trait IntoOutputPredicate<P>
 where
     P: predicates::Predicate<[u8]>,
@@ -398,7 +420,10 @@ where
 }
 
 // Keep `predicates` concrete Predicates out of our public API.
-/// Predicate used by `IntoOutputPredicate` for bytes
+/// [Predicate][Predicate] used by [`IntoOutputPredicate`][IntoOutputPredicate] for bytes.
+///
+/// [IntoOutputPredicate]: trait.IntoOutputPredicate.html
+/// [Predicate]: https://docs.rs/predicates/0.5.2/predicates/trait.Predicate.html
 #[derive(Debug)]
 pub struct BytesContentOutputPredicate(predicates::ord::EqPredicate<&'static [u8]>);
 
@@ -430,7 +455,10 @@ impl IntoOutputPredicate<BytesContentOutputPredicate> for &'static [u8] {
 }
 
 // Keep `predicates` concrete Predicates out of our public API.
-/// Predicate used by `IntoOutputPredicate` for `str`
+/// [Predicate][Predicate] used by [`IntoOutputPredicate`][IntoOutputPredicate] for `str`.
+///
+/// [IntoOutputPredicate]: trait.IntoOutputPredicate.html
+/// [Predicate]: https://docs.rs/predicates/0.5.2/predicates/trait.Predicate.html
 #[derive(Debug, Clone)]
 pub struct StrContentOutputPredicate(
     predicates::str::Utf8Predicate<predicates::str::DifferencePredicate>,

src/cargo.rs

@@ -1,12 +1,14 @@
 //! Simplify running `bin`s in a Cargo project.
 //!
-//! `CommandCargoExt` is an extension trait for `std::process::Command` to easily launch a crate's
+//! [`CommandCargoExt`][CommandCargoExt] is an extension trait for [`Command`][Command] to easily launch a crate's
 //! binaries.
 //!
 //! In addition, the underlying functions for looking up the crate's binaries are exposed to allow
 //! for optimizations, if needed.
 //!
-//! # Simple Example
+//! # Examples
+//!
+//! Simple case:
 //!
 //! ```rust
 //! use assert_cmd::prelude::*;
@@ -18,7 +20,7 @@
 //!     .unwrap();
 //! ```
 //!
-//! # Caching Example
+//! Caching the binary's location:
 //!
 //! ```rust
 //! use assert_cmd::prelude::*;
@@ -30,9 +32,11 @@
 //!     .unwrap();
 //! ```
 //!
-//! Tip: Use [`lazy_static][lazy_static] to cache `bin_under_test` across test functions.
+//! Tip: Use [`lazy_static`][lazy_static] to cache `bin_under_test` across test functions.
 //!
 //! [lazy_static]: https://crates.io/crates/lazy_static
+//! [CommandCargoExt]: trait.CommandCargoExt.html
+//! [Command]: https://doc.rust-lang.org/std/process/struct.Command.html
 
 use std::error::Error;
 use std::ffi;
@@ -42,12 +46,14 @@ use std::process;
 
 use escargot;
 
-/// Create a `Command` for a `bin` in the Cargo project.
+/// Create a [`Command`][Command] for a `bin` in the Cargo project.
+///
+/// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html
 pub trait CommandCargoExt
 where
     Self: Sized,
 {
-    /// Create a `Command` to run the crate's main binary.
+    /// Create a [`Command`][Command] to run the crate's main binary.
     ///
     /// Note: only works if there one bin in the crate.
     ///
@@ -62,9 +68,11 @@ where
     ///     .unwrap()
     ///     .unwrap();
     /// ```
+    ///
+    /// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html
     fn main_binary() -> Result<Self, CargoError>;
 
-    /// Create a `Command` to run a specific binary of the current crate.
+    /// Create a [`Command`][Command] to run a specific binary of the current crate.
     ///
     /// # Examples
     ///
@@ -77,9 +85,11 @@ where
     ///     .unwrap()
     ///     .unwrap();
     /// ```
+    ///
+    /// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html
     fn cargo_bin<S: AsRef<ffi::OsStr>>(name: S) -> Result<Self, CargoError>;
 
-    /// Create a `Command` to run a specific example of the current crate.
+    /// Create a [`Command`][Command] to run a specific example of the current crate.
     ///
     /// # Examples
     ///
@@ -92,6 +102,8 @@ where
     ///     .unwrap()
     ///     .unwrap();
     /// ```
+    ///
+    /// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html
     fn cargo_example<S: AsRef<ffi::OsStr>>(name: S) -> Result<Self, CargoError>;
 }
 

src/cmd.rs

@@ -4,7 +4,7 @@ use errors::dump_buffer;
 use errors::OutputError;
 use errors::OutputResult;
 
-/// Convert an `Output` to a `OutputResult`.
+/// Convert an [`Output`][Output] to an [`OutputResult`][OutputResult].
 ///
 /// # Examples
 ///
@@ -18,11 +18,14 @@ use errors::OutputResult;
 ///     .ok();
 /// assert!(result.is_ok());
 /// ```
+///
+/// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
+/// [OutputResult]: type.OutputResult.html
 pub trait OutputOkExt
 where
     Self: ::std::marker::Sized,
 {
-    /// Convert an `std::process::Output` into an `OutputResult`.
+    /// Convert an [`Output`][Output] to an [`OutputResult`][OutputResult].
     ///
     /// # Examples
     ///
@@ -36,9 +39,12 @@ where
     ///     .ok();
     /// assert!(result.is_ok());
     /// ```
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
+    /// [OutputResult]: type.OutputResult.html
     fn ok(self) -> OutputResult;
 
-    /// Unwrap a `std::process::Output` but with a prettier message than `.ok().unwrap()`.
+    /// Unwrap a [`Output`][Output] but with a prettier message than `.ok().unwrap()`.
     ///
     /// # Examples
     ///
@@ -51,14 +57,16 @@ where
     ///     .args(&["42"])
     ///     .unwrap();
     /// ```
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
     fn unwrap(self) -> process::Output {
         match self.ok() {
             Ok(output) => output,
             Err(err) => panic!("{}", err),
         }
     }
 
-    /// Unwrap a `std::process::Output` but with a prettier message than `.ok().unwrap()`.
+    /// Unwrap a [`Output`][Output] but with a prettier message than `ok().err().unwrap()`.
     ///
     /// # Examples
     ///
@@ -72,6 +80,8 @@ where
     ///     .env("exit", "42")
     ///     .unwrap_err();
     /// ```
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
     fn unwrap_err(self) -> OutputError {
         match self.ok() {
             Ok(output) => panic!(

src/errors.rs

@@ -3,7 +3,9 @@ use std::fmt;
 use std::process;
 use std::str;
 
-/// `std::process::Output` represented as a `Result`.
+/// [`Output`][Output] represented as a [`Result`][Result].
+///
+/// Generally produced by [`OutputOkExt`][OutputOkExt].
 ///
 /// # Examples
 ///
@@ -17,9 +19,15 @@ use std::str;
 ///     .ok();
 /// assert!(result.is_ok());
 /// ```
+///
+/// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
+/// [Result]: https://doc.rust-lang.org/std/result/enum.Result.html
+/// [OutputOkExt]: trait.OutputOkExt.html
 pub type OutputResult = Result<process::Output, OutputError>;
 
-/// `Command` error.
+/// [`Command`][Command] error.
+///
+/// Generally produced by [`OutputOkExt`][OutputOkExt].
 ///
 /// # Examples
 ///
@@ -33,6 +41,9 @@ pub type OutputResult = Result<process::Output, OutputError>;
 ///     .env("exit", "42")
 ///     .unwrap_err();
 /// ```
+///
+/// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html
+/// [OutputOkExt]: trait.OutputOkExt.html
 #[derive(Debug)]
 pub struct OutputError {
     cmd: Option<String>,
@@ -41,7 +52,10 @@ pub struct OutputError {
 }
 
 impl OutputError {
-    /// Convert `std::process::Output` into an `Error`.
+    /// Convert [`Output`][Output] into an [`Error`][Error].
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
+    /// [Error]: https://doc.rust-lang.org/std/error/trait.Error.html
     pub fn new(output: process::Output) -> Self {
         Self {
             cmd: None,
@@ -50,7 +64,9 @@ impl OutputError {
         }
     }
 
-    /// For errors that happen in creating a `std::process::Output`.
+    /// For errors that happen in creating a [`Output`][Output].
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
     pub fn with_cause<E>(cause: E) -> Self
     where
         E: Error + Send + Sync + 'static,
@@ -74,7 +90,7 @@ impl OutputError {
         self
     }
 
-    /// Access the contained `std::process::Output`.
+    /// Access the contained [`Output`][Output].
     ///
     /// # Examples
     ///
@@ -92,6 +108,8 @@ impl OutputError {
     ///     .unwrap();
     /// assert_eq!(Some(42), output.status.code());
     /// ```
+    ///
+    /// [Output]: https://doc.rust-lang.org/std/process/struct.Output.html
     pub fn as_output(&self) -> Option<&process::Output> {
         match self.cause {
             OutputCause::Expected(ref e) => Some(&e.output),
@@ -113,6 +131,7 @@ impl Error for OutputError {
         }
     }
 }
+
 impl fmt::Display for OutputError {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         if let Some(ref cmd) = self.cmd {
@@ -144,7 +163,6 @@ impl fmt::Display for OutputCause {
     }
 }
 
-/// Wrap `Output` to be `Dislay`able.
 #[derive(Debug)]
 struct Output {
     output: process::Output,