Add docstring comments to all the anthology functions

Add docstring comments for all the incant function throughout the
anthology, documenting what each function does, and an example of it's
shell command.

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,