From 0bc9fc5c605a1247143db4af54782427de5df3c5 Mon Sep 17 00:00:00 2001
From: Rory Dudley
Date: Wed, 28 Feb 2024 22:50:46 -0700
Subject: Add doc comments for incant_ functions

Added documentation comments for the Meter::incant_ functions,
describing how each function operates.
---
 src/recite.rs | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

(limited to 'src')

diff --git a/src/recite.rs b/src/recite.rs
index c8364e5..9860eff 100644
--- a/src/recite.rs
+++ b/src/recite.rs
@@ -49,6 +49,19 @@ impl fmt::Display for Meter {
 }
 
 impl Meter {
+    /// Recite a verse with [Meter::None]
+    ///
+    /// Call this function on a [Verse] with a meter of type [Meter::None].
+    /// This forks into a child process, calls the `verb` (i.e. program)
+    /// that was specified in the [Verse], then waits for that program to
+    /// complete. If the last [Verse] piped its contents into `out`, it will
+    /// be piped into the STDIN of this [Verse]. If all Rust code is called
+    /// successfully, return the exit code of the process. Otherwise, return a
+    /// [std::io::Error].
+    ///
+    /// # Arguments
+    /// * `verse: &Verse` - The verse to recite
+    /// * `out: &mut String` - A string that may have output from the last command
     fn incant_none(verse: &Verse, out: &mut String) -> Result<i32, io::Error> {
         let child = task!(verse, out);
 
@@ -61,6 +74,20 @@ impl Meter {
         Ok(output.status.code().unwrap_or(0))
     }
 
+    /// Recite a verse with [Meter::None]
+    ///
+    /// Call this function on a [Verse] with a meter of type [Meter::None].
+    /// This forks into a child process, calls the `verb` (i.e. program)
+    /// that was specified in the [Verse], then waits for that program to
+    /// complete. If the last [Verse] piped its contents into `out`, it will
+    /// be piped into the STDIN of this [Verse]. Then, the contents of this
+    /// processes' STDOUT are stored in `out`. If all Rust code is called
+    /// successfully, return the exit code of the process. Otherwise, return a
+    /// [std::io::Error].
+    ///
+    /// # Arguments
+    /// * `verse: &Verse` - The verse to recite
+    /// * `out: &mut String` - A string that may have output from the last command
     fn incant_couplet(verse: &Verse, out: &mut String) -> Result<i32, io::Error> {
         let child = ctask!(verse, out);
 
@@ -79,6 +106,20 @@ impl Meter {
         Ok(output.status.code().unwrap_or(0))
     }
 
+    /// Recite a verse with [Meter::Quiet]
+    ///
+    /// Call this function on a [Verse] with a meter of type [Meter::Quiet].
+    /// This forks a child process into the background. It then registers a
+    /// `SIGCHLD` handler, making sure to do so for each PID in the `pids`
+    /// Vec. If the last [Verse] piped its contents into `out`, it will be
+    /// piped into the STDIN of this [Verse]. If all Rust code is called
+    /// successfully, return the exit code of the process. Otherwise, return a
+    /// [std::io::Error].
+    ///
+    /// # Arguments
+    /// * `verse: &Verse` - The verse to recite
+    /// * `out: &mut String` - A string that may have output from the last command
+    /// * `pids: Arc<Mutex<Vec<i32>>>` - A vector that stores the PIDs of all background processes that belong to the shell
     fn incant_quiet(
         verse: &Verse,
         out: &mut String,
@@ -109,10 +150,12 @@ impl Meter {
         Ok(0)
     }
 
+    /// Alias to [Meter::incant_none]
     fn incant_and(verse: &Verse, out: &mut String) -> Result<i32, io::Error> {
         Meter::incant_none(verse, out)
     }
 
+    /// Alias to [Meter::incant_none]
     fn incant_string(verse: &Verse, out: &mut String) -> Result<i32, io::Error> {
         Meter::incant_none(verse, out)
     }
-- 
cgit v1.2.3