Add/update doc comments

This patch update a ton of the documentation comments throughout the
codebase, refactoring some areas, and adding new comments to others.

1 files changed, 6 insertions, 3 deletions

diff --git a/src/poem/anthology/cd.rs b/src/poem/anthology/cd.rs
index bdf04f6..4427536 100644
--- a/src/poem/anthology/cd.rs
+++ b/src/poem/anthology/cd.rs
@@ -5,13 +5,16 @@ use std::process::{ExitStatus, Output};
 /// cd
 ///
 /// The builtin `cd` command. Used to change directories. This must be
-/// implemented by the shell, since the `pwd` is context sensitive within a
-/// process. If no arguments are given, `cd` will take the user back to their
-/// home directory (i.e. `~`).
+/// implemented by the shell, since the present working directory
+/// (`pwd`) is context sensitive within a process. If no arguments are
+/// given, `cd` will take the user back to their home directory (i.e.
+/// `~` / `$HOME`).
 ///
 /// # Shell Example
 /// ```sh
 /// cd ~/.config # Change into /home/<user>/.config
+/// cd / # Change into the root directory
+/// cd # Change into the home directory
 /// ```
 pub fn incant(clause: &Option<Vec<String>>, uerr: bool) -> Output {
     let status;