From 6f7b03981ae2c9b79c8d6125e1998bcc67f59fc2 Mon Sep 17 00:00:00 2001
From: Rory Dudley
Date: Mon, 20 May 2024 14:05:48 -0600
Subject: Update doc comments for Poem::read functions

Update documentation comments for the Poem::read() function, as well as
the Poem::add() function (which is crucial for read()).
---
 src/poem/read.rs | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

(limited to 'src/poem')

diff --git a/src/poem/read.rs b/src/poem/read.rs
index 3c4a720..c6596ad 100644
--- a/src/poem/read.rs
+++ b/src/poem/read.rs
@@ -56,7 +56,20 @@ impl Appendable for Poem {
     /// Push a [Verse] to the [Poem]
     ///
     /// Push a [Verse] to the [Poem] after checking that the [Verse] is not
-    /// empty. Also sets the meter of the [Verse].
+    /// empty. It also:
+    ///  - sets the meter of the [Verse],
+    ///  - determines the couplet status of the [Verse],
+    ///  - and checks for aliases associated the the [Verse]'s verb.
+    ///
+    /// Once the [Verse] is pushed to the [Poem], the verse stack is cleared.
+    ///
+    /// # Examples
+    /// ```
+    /// ...
+    /// verse.push("cat");
+    /// verse.push("Cargo.toml");
+    /// poem.add(&mut verse, Rune::None, &mut env);
+    /// ```
     fn add(
         &mut self,
         verse: &mut Self::Type,
@@ -143,8 +156,8 @@ impl Readable for Poem {
     ///
     /// Takes a shell command/program or file and converts it to a
     /// machine-runnable [Poem]. If there is a parse error, [Poem::read] may
-    /// return a [Mishap]. See [Poem::recite][super::recite] for how each
-    /// [Verse] in a [Poem] is called.
+    /// return a [Mishap]. See [Poem::recite][super::recite] or [Verse::incant]
+    /// for how each [Verse] in a [Poem] is called.
     fn read(poetry: String, env: &mut Environment) -> Result<Poem, Mishap> {
         // Get all the characters in the input string as an iterator
         let mut chars = poetry.chars().into_iter();
-- 
cgit v1.2.3