From b8338719e2cc2138bc67c10ad56fb707f5e3b546 Mon Sep 17 00:00:00 2001
From: Rory Dudley
Date: Sun, 30 Jun 2024 20:09:26 -0600
Subject: 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.
---
 src/poem/anthology/alias.rs  |  4 ++--
 src/poem/anthology/cd.rs     |  9 ++++++---
 src/poem/anthology/export.rs |  4 ++--
 src/poem/anthology/source.rs |  4 ++--
 src/poem/anthology/which.rs  | 12 ++++++++++++
 5 files changed, 24 insertions(+), 9 deletions(-)

(limited to 'src/poem/anthology')

diff --git a/src/poem/anthology/alias.rs b/src/poem/anthology/alias.rs
index 0746b59..fdd1224 100644
--- a/src/poem/anthology/alias.rs
+++ b/src/poem/anthology/alias.rs
@@ -5,8 +5,8 @@ use std::process::{ExitStatus, Output};
 
 /// alias
 ///
-/// The builtin `alias` command. Used to monikers for other verbs, or entire
-/// verses.
+/// The builtin `alias` command. Used to monikers for other verbs, or
+/// entire verses.
 ///
 /// # Shell Example
 /// ```sh
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;
diff --git a/src/poem/anthology/export.rs b/src/poem/anthology/export.rs
index 35a24ae..4c8e46d 100644
--- a/src/poem/anthology/export.rs
+++ b/src/poem/anthology/export.rs
@@ -5,8 +5,8 @@ use std::process::{ExitStatus, Output};
 
 /// export
 ///
-/// The builtin `export` command. Used to set global environment variables for
-/// the current instance of the shell.
+/// The builtin `export` command. Used to set global environment
+/// variables for the current instance of the shell.
 ///
 /// # Aliases
 /// * export
diff --git a/src/poem/anthology/source.rs b/src/poem/anthology/source.rs
index 0ed759c..fc27caf 100644
--- a/src/poem/anthology/source.rs
+++ b/src/poem/anthology/source.rs
@@ -6,8 +6,8 @@ use std::process::{ExitStatus, Output};
 
 /// source
 ///
-/// The builtin `source` command. Used to change the shell's global environment
-/// state via a `.sh` or `.dwvsh` file.
+/// The built-in `source` command. Used to change the shell's global
+/// environment state via a `.sh` or `.dwvsh` file.
 ///
 /// # Shell Examples
 /// ```sh
diff --git a/src/poem/anthology/which.rs b/src/poem/anthology/which.rs
index 0872dda..9a1708a 100644
--- a/src/poem/anthology/which.rs
+++ b/src/poem/anthology/which.rs
@@ -4,6 +4,18 @@ use crate::poem::Verse;
 use std::os::unix::process::ExitStatusExt;
 use std::process::{ExitStatus, Output};
 
+/// which
+///
+/// The built-in `which` command. Used to check what program would be
+/// called when not providing a full path. On Linux, it seems most
+/// distros ship with a standalone `which` program. BSD systems, on the
+/// other hand, tend to just use the shell built-in.
+///
+/// # Shell Examples
+/// ```sh
+/// which ls # -> /bin/ls
+/// which exit # -> shell built-in command
+/// ```
 pub fn incant(clause: &Option<Vec<String>>, uout: bool, uerr: bool, env: &Environment) -> Output {
     let mut status = 0;
     let mut out: Vec<u8> = Vec::new();
-- 
cgit v1.2.3