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/alias.rs  | 18 ++++++++++++++++++
 src/poem/anthology/cd.rs     | 11 +++++++++++
 src/poem/anthology/exit.rs   |  7 +++++++
 src/poem/anthology/export.rs | 23 +++++++++++++++++++++++
 src/poem/anthology/source.rs |  9 +++++++++
 5 files changed, 68 insertions(+)

(limited to 'src/poem/anthology')

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