From e06d529c3a9624f7d5db2b0054f88af6062757cc Mon Sep 17 00:00:00 2001
From: Rory Dudley
Date: Mon, 20 May 2024 14:37:25 -0600
Subject: Updated/added doc comments for the Verse element

Added definitions of fields for the Verse struct, and updated its
wording to accomodate for the type change of the couplet field.

Updated the wording of Verse::add() to make it more verbose, and also
added descriptions of the arguments, alongside some example usage.

Added documentation comments for the Verse::incant() function.
---
 src/poem/elements/verse.rs | 65 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 61 insertions(+), 4 deletions(-)

(limited to 'src')

diff --git a/src/poem/elements/verse.rs b/src/poem/elements/verse.rs
index b0d451b..5694b55 100644
--- a/src/poem/elements/verse.rs
+++ b/src/poem/elements/verse.rs
@@ -31,7 +31,41 @@ impl Verse {
     /// Create a new [Verse]
     ///
     /// Returns a new [Verse], with an empty [Stanza], a meter of [Rune::None],
-    /// and `couplet` set to `false`.
+    /// and `couplet` set to 0.
+    ///
+    /// # Fields
+    /// stanza - The command (a `verb()` and a `clause()`)
+    /// couplet - Indicates couplet status
+    ///           0: Not a couplet (`cat Cargo.toml`)
+    ///           1: Left side of a couplet (`cat Cargo.toml | ...`)
+    ///           2: Right side of a couplet (`... | lolcat`)
+    ///           3: Sandwiched between couplets (`... | grep Ca | ...`)
+    /// io - A list of IO operations ([Rune::Read], [Rune::Write], etc.)
+    /// ip - A list of filenames for reading into STDIN when:
+    ///      [Rune::Read]
+    ///      is specified
+    /// op - A list of filenames for redirecting STDOUT to when:
+    ///      [Rune::Write],
+    ///      [Rune::WriteAll],
+    ///      [Rune::Addendum],
+    ///      and/or [Rune::AddendumAll]
+    ///      is specified
+    /// ep - A list of filenames for redirecting STDERR to when:
+    ///      [Rune::Write2],
+    ///      [Rune::WriteAll],
+    ///      [Rune::Addendum2],
+    ///      and/or [Rune::AddendumAll]
+    ///      is specified
+    /// poems - Internal commands to run before the [Verse] is recited
+    ///         ([Rune::Poem]).
+    /// meter - Determines how the verse is recited in relation to the other
+    ///         verses in the [Poem].
+    ///         [Rune::None] -> Run the command and print the output
+    ///         [Rune::Couplet] -> Pipe the output of this verse into the next
+    ///         [Rune::Quiet] -> Run in the background
+    ///         [Rune::And] -> Run the next verse only if this verse succeeds
+    ///         [Rune::Continue] -> Run the next verse, regardless of whether
+    ///                             or not this verse succeeds
     pub fn new() -> Self {
         Verse {
             stanza: Stanza::new(),
@@ -90,9 +124,25 @@ impl Verse {
 
     /// Push a word to the [Verse]'s [Stanza]
     ///
-    /// Push a word to the [Stanza] after performing a few extra checks, such
-    /// as whether or not the word is empty, or if the word should be
-    /// interpreted as an environment variable.
+    /// Push a word to the [Verse]'s [Stanza], or one of its IO channels. If
+    /// `word` is empty, this function will simply return without performing
+    /// any operations. A channel of [None] will push to the [Verse]'s
+    /// [Stanza], while IO [Rune]s will determine which IO channel a word will
+    /// get pushed onto.
+    ///
+    /// # Arguments
+    /// word - The word to push onto the [Stanza]/channel
+    /// channel - Specifiy which channel to use
+    ///
+    /// # Examples
+    /// ```
+    /// word.push("c");
+    /// word.push("a");
+    /// word.push("t");
+    /// verse.add(&mut word, None); // Pushes onto [Stanza]
+    /// verse.add(&mut word, Some(Rune::Write)); // Pushes onto [op]
+    /// verse.add(&mut word, Some(Rune::WriteAll)); // Pushes onto [op], [ep]
+    /// ```
     pub fn add(&mut self, word: &mut Word, channel: Option<Rune>) {
         // Do nothing if the stack is empty
         if word.is_empty() {
@@ -172,6 +222,13 @@ impl Verse {
         true
     }
 
+    /// Run a command
+    ///
+    /// The [Poem]::recite() function calls this [Verse::incant] function for
+    /// each verse it contains. This function handles the actual setup and
+    /// spawning (forking) of a new process specified in the [Verse]. It will
+    /// also run IO operations for the verse, and setup appropriate coupling,
+    /// as per the [Verse]'s own details, contained throughout its fields.
     pub fn incant(
         &mut self,
         out: &mut Vec<u8>,
-- 
cgit v1.2.3