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, 12 insertions, 0 deletions

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();