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.

1 files changed, 17 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 {