Add/update doc comments

This patch update a ton of the documentation comments throughout the
codebase, refactoring some areas, and adding new comments to others.

1 files changed, 33 insertions, 6 deletions

diff --git a/src/poem/read.rs b/src/poem/read.rs
index 0418738..6d7550b 100644
--- a/src/poem/read.rs
+++ b/src/poem/read.rs
@@ -8,10 +8,35 @@ use crate::compose::Environment;
 use crate::{poem, remark, string};
 use parse::next;
 
+/// Custom errors for the parser ([read()][crate::poem::read])
 #[derive(Debug, PartialEq, Eq)]
 pub enum Mishap {
+    /// Generic parser error
     ParseMishap(usize, usize, char),
+
+    /// IO operation parse errors
+    ///
+    /// Raised when an IO operation is specified, but a filepath was not
+    /// given.
+    ///
+    /// # Examples
+    /// ```sh
+    /// cat < # No file specified for Rune::Read
+    /// cat file.txt >> # No file specified for Rune::Addendum
+    /// ```
     IOMishap(usize, usize, char),
+
+    /// Missing end character
+    ///
+    /// Some [Rune]s consists of two characters, that may contain other
+    /// characters between them (i.e. [String][Rune::String]). This is
+    /// raised when the ending character was left out.
+    ///
+    /// # Examples
+    /// ```sh
+    /// echo 'Hello # Ending ' character is missing
+    /// mv file.txt hello.txt" # Beginning " character is missing
+    /// ```
     PartialMishap(usize, usize, char),
 }
 
@@ -55,13 +80,14 @@ impl Appendable for Poem {
 
     /// Push a [Verse] to the [Poem]
     ///
-    /// Push a [Verse] to the [Poem] after checking that the [Verse] is not
-    /// empty. It also:
+    /// Push a [Verse] to the [Poem] after checking that the [Verse] is
+    /// not 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.
+    /// Once the [Verse] is pushed to the [Poem], the verse stack is
+    /// cleared.
     ///
     /// # Examples
     /// ```
@@ -157,9 +183,10 @@ impl Readable for Poem {
     /// Parse a [Poem] from a raw [String] input
     ///
     /// 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] or [Verse::incant]
-    /// for how each [Verse] in a [Poem] is called.
+    /// machine-runnable [Poem]. If there is a parse error,
+    /// [read()][Poem::read] may return a [Mishap]. See
+    /// [recite()][crate::poem::recite] or [incant()][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();