From 791b61f97e3ee12dfd765f5e23edd5df527eb803 Mon Sep 17 00:00:00 2001
From: Rory Dudley
Date: Sun, 31 Mar 2024 00:50:03 -0600
Subject: 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.
---
 src/poem/anthology.rs | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'src/poem/anthology.rs')

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 {
-- 
cgit v1.2.3