From dc2f50292d616f25a4cf6594afa220cc0578fd86 Mon Sep 17 00:00:00 2001
From: Gavin Panella <gavinpanella@gmail.com>
Date: Tue, 2 Jul 2024 14:07:23 +0200
Subject: [PATCH] Improve documentation

---
 README.md  | 22 +++++++++++++---------
 src/lib.rs |  7 ++++---
 src/sh.rs  |  4 +++-
 3 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index f630a4c..196d950 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,8 @@ Bash's _word splitting_), paths (Bash's _pathname expansion_), shell
 metacharacters, function calls, or other syntax. This is frequently not as
 simple as wrapping a string in quotes.
 
-For now this package implements escaping for `/bin/sh`-like shells including
-[Dash][dash], [GNU Bash][gnu-bash], [Z Shell][z-shell], and [fish][]. Please
-read the documentation for each module to learn about some limitations and
-caveats.
+This package implements escaping for [GNU Bash][gnu-bash], [Z Shell][z-shell],
+[fish][], and `/bin/sh`-like shells including [Dash][dash].
 
 [dash]: https://en.wikipedia.org/wiki/Almquist_shell#dash
 [gnu-bash]: https://www.gnu.org/software/bash/
@@ -28,16 +26,22 @@ enough that you must use [`Fish`] for fish scripts.
 
 ## Examples
 
-When quoting using raw bytes it can be convenient to call [`Bash`]'s, [`Sh`]'s,
-and [`Fish`]'s associated functions directly:
+When quoting using raw bytes it can be convenient to call [`Sh`]'s, [`Dash`]'s,
+[`Bash`]'s, [`Fish`]'s, and [`Zsh`]'s associated functions directly:
 
 ```rust
-use shell_quote::{Bash, Sh, Fish};
-assert_eq!(Bash::quote("foobar"), b"foobar");
+use shell_quote::{Bash, Dash, Fish, Sh, Zsh};
+// No quoting is necessary for simple strings.
 assert_eq!(Sh::quote("foobar"), b"foobar");
+assert_eq!(Dash::quote("foobar"), b"foobar");  // `Dash` is an alias for `Sh`
+assert_eq!(Bash::quote("foobar"), b"foobar");
+assert_eq!(Zsh::quote("foobar"), b"foobar");   // `Zsh` is an alias for `Bash`
 assert_eq!(Fish::quote("foobar"), b"foobar");
-assert_eq!(Bash::quote("foo bar"), b"$'foo bar'");
+// In all shells, quoting is necessary for strings with spaces.
 assert_eq!(Sh::quote("foo bar"), b"foo' bar'");
+assert_eq!(Dash::quote("foo bar"), b"foo' bar'");
+assert_eq!(Bash::quote("foo bar"), b"$'foo bar'");
+assert_eq!(Zsh::quote("foo bar"), b"$'foo bar'");
 assert_eq!(Fish::quote("foo bar"), b"foo' bar'");
 ```
 
diff --git a/src/lib.rs b/src/lib.rs
index 4a2edb6..964f30c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -140,9 +140,10 @@ pub trait Quoter: quoter::QuoterSealed {}
 
 /// A string of bytes that can be quoted/escaped.
 ///
-/// This is used by many methods in this crate as a generic `Into<Quotable>`
-/// constraint. Why not accept [`AsRef<[u8]>`] instead? The ergonomics of that
-/// approach were not so good. For example, quoting [`OsString`]/[`OsStr`] and
+/// This is used by many methods in this crate as a generic
+/// [`Into<Quotable>`][`Into`] constraint. Why not accept
+/// [`AsRef<[u8]>`][`AsRef`] instead? The ergonomics of that approach were not
+/// so good. For example, quoting [`OsString`]/[`OsStr`] and
 /// [`PathBuf`]/[`Path`] didn't work in a natural way.
 pub struct Quotable<'a> {
     pub(crate) bytes: &'a [u8],
diff --git a/src/sh.rs b/src/sh.rs
index 7d96965..10b81d8 100644
--- a/src/sh.rs
+++ b/src/sh.rs
@@ -60,7 +60,9 @@ use crate::{ascii::Char, quoter::QuoterSealed, Quotable, Quoter};
 /// >   (\).  The backslash inside double quotes is historically weird, and
 /// >   serves to quote only the following characters:
 /// >
-/// >     $ ` " \ <newline>.
+/// >   ```text
+/// >   $ ` " \ <newline>.
+/// >   ```
 /// >
 /// >   Otherwise it remains literal.
 ///