6 files changed, 85 insertions, 1 deletions

diff --git a/src/poem/anthology.rs b/src/poem/anthology.rs
index 2a2f62a..9a0d2e4 100644
--- a/src/poem/anthology.rs
+++ b/src/poem/anthology.rs
@@ -13,7 +13,7 @@ static INDEX: [&str; 7] = [
 
 /// Lookup the index of a built-in command
 ///
-/// Looks up the index of a built-in command in [INDEX], accounting for aliases
+/// Looks up the index of a built-in command in [INDEX], accounting for aliases.
 pub fn lookup(verb: &str) -> Option<usize> {
     let verb = match verb {
         "quit" => "exit",  // Alias 'quit' to 'exit'
@@ -23,6 +23,22 @@ pub fn lookup(verb: &str) -> Option<usize> {
     INDEX.iter().position(|v| v.to_string() == verb)
 }
 
+/// Run a builtin command, based on its verb
+///
+/// Use [lookup] to check if a verb is in the anthology's index (i.e. is a
+/// builtin), then call this with the current verse, the index found by
+/// [lookup], and the shell's global environment state.
+///
+/// # Example
+/// ```
+/// let index = anthology::lookup(verse.verb());
+/// if index.is_some() {
+///     anthology::incant(&verse, index.unwrap(), env);
+/// } else {
+///     // Run an external command
+///     ...
+/// }
+/// ```
 pub fn incant(verse: &Verse, index: usize, env: &mut Environment) -> i32 {
     let verb = INDEX[index];
     match verb {
diff --git a/src/poem/anthology/alias.rs b/src/poem/anthology/alias.rs
index 6a8e739..96682db 100644
--- a/src/poem/anthology/alias.rs
+++ b/src/poem/anthology/alias.rs
@@ -1,6 +1,15 @@
 use crate::poem::Verse;
 use std::collections::HashMap;
 
+/// alias
+///
+/// The builtin `alias` command. Used to monikers for other verbs, or entire
+/// verses.
+///
+/// # Shell Example
+/// ```sh
+/// alias vim=nvim
+/// ```
 pub fn incant(verse: &Verse, aliases: &mut HashMap<String, String>) -> i32 {
     match verse.clause() {
         Some(clause) => {
@@ -31,6 +40,15 @@ pub fn incant(verse: &Verse, aliases: &mut HashMap<String, String>) -> i32 {
     0
 }
 
+/// unalias
+///
+/// The builtin `unalias` command. Used to remove shell monikers, since `alias`
+/// may be called with an empty string as the value.
+///
+/// # Shell Example
+/// ```sh
+/// unalias vim
+/// ```
 pub fn unincant(verse: &Verse, aliases: &mut HashMap<String, String>) -> i32 {
     match verse.clause() {
         Some(clause) => {
diff --git a/src/poem/anthology/cd.rs b/src/poem/anthology/cd.rs
index d3a1998..5b39359 100644
--- a/src/poem/anthology/cd.rs
+++ b/src/poem/anthology/cd.rs
@@ -1,6 +1,17 @@
 use crate::poem::Verse;
 use std::env;
 
+/// 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. `~`).
+///
+/// # Shell Example
+/// ```sh
+/// cd ~/.config # Change into /home/<user>/.config
+/// ```
 pub fn incant(verse: &Verse) -> i32 {
     let path = match verse.clause() {
         Some(path) => path[0].to_string(),
diff --git a/src/poem/anthology/exit.rs b/src/poem/anthology/exit.rs
index ecb14f1..46fe13c 100644
--- a/src/poem/anthology/exit.rs
+++ b/src/poem/anthology/exit.rs
@@ -1,5 +1,12 @@
 use std::process::exit;
 
+/// exit
+///
+/// The builtin `exit` command. Used to quit the shell.
+///
+/// # Aliases
+/// * exit
+/// * quit
 pub fn incant() -> i32 {
     exit(0);
 }
diff --git a/src/poem/anthology/export.rs b/src/poem/anthology/export.rs
index a61935c..dfbaf81 100644
--- a/src/poem/anthology/export.rs
+++ b/src/poem/anthology/export.rs
@@ -1,6 +1,19 @@
 use crate::poem::Verse;
 use std::env;
 
+/// export
+///
+/// The builtin `export` command. Used to set global environment variables for
+/// the current instance of the shell.
+///
+/// # Aliases
+/// * export
+/// * set
+///
+/// # Shell Examples
+/// ```sh
+/// export FOO=BAR
+/// ```
 pub fn incant(verse: &Verse) -> i32 {
     match verse.clause() {
         Some(clause) => {
@@ -22,6 +35,16 @@ pub fn incant(verse: &Verse) -> i32 {
     0
 }
 
+/// unset
+///
+/// The builtin `unset` command. Used to remove global environment variables
+/// from the current instance of the shell, since `export` may be called with
+/// an empty string as the value.
+///
+/// # Shell Examples
+/// ```sh
+/// unset FOO
+/// ```
 pub fn unincant(verse: &Verse) -> i32 {
     match verse.clause() {
         Some(clause) => {
diff --git a/src/poem/anthology/source.rs b/src/poem/anthology/source.rs
index b4148cb..ed4ed13 100644
--- a/src/poem/anthology/source.rs
+++ b/src/poem/anthology/source.rs
@@ -3,6 +3,15 @@ use crate::poem::Verse;
 use crate::poem::{read::Readable, recite::Reciteable, Poem};
 use std::fs;
 
+/// source
+///
+/// The builtin `source` command. Used to change the shell's global environment
+/// state via a `.sh` or `.dwvsh` file.
+///
+/// # Shell Examples
+/// ```sh
+/// source ~/.dwvshrc
+/// ```
 pub fn incant(verse: &Verse, env: &mut Environment) -> i32 {
     let files = match verse.clause() {
         Some(clause) => clause,