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()).

1 files changed, 16 insertions, 3 deletions

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();