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, 67 insertions, 49 deletions

diff --git a/src/poem/elements/rune.rs b/src/poem/elements/rune.rs
index 688043d..64e3326 100644
--- a/src/poem/elements/rune.rs
+++ b/src/poem/elements/rune.rs
@@ -2,57 +2,75 @@ use core::fmt;
 
 /// Describes one or two characters from the input
 ///
-/// [Rune]s are a way to mark special characters from the input string (i.e.
-/// poetry). Some [Rune]s are special--as they denote the end of a [Verse]--
-/// and are refered to as a Meter. For instance, `Addendum`, `Couplet`,
-/// `Quiet`, and `And`, are all meters. Meters also determine how the
-/// [Stanza][super::stanza::Stanza] should be interpreted. For instance, a
-/// [Stanza][super::stanza::Stanza] that is piped needs to have
-/// its `STDOUT` captured (rather than printing out to the terminal), and
-/// subsequently sent to the next [Verse] in the [Poem][super::super::Poem].
-///
-/// # Values
-/// * `None` - A shell command with no additional actions (the end of a poem)
-/// * `Pause` - The space character, to dilineate words (` `)
-/// * `Path` - The forward slash character, to dilineate paths (`/`)
-/// * `Remark` - Indicates a single line comment (`#`)
-/// * `String` - Interpret all character as one large
-///              [Word][super::word::Word] (`'` or `"`)
-/// * `Poem` - A subcommand to run first (`\``)
-/// * `Read` - Read files into STDIN (`<`)
-/// * `Write` - Write STDOUT to a file (`>`)
-/// * `Write2` - Write STDERR to a file (`2>`)
-/// * `WriteAll` - Write both STDOUT and STDERR to a file (`&>`)
-/// * `Addendum` - Append STDOUT to a file (`>>`)
-/// * `Addendum2` - Append STDERR to a file (`2>>`)
-/// * `AddendumAll` - Append both STDOUT and STDERR to a file (`&>>`)
-/// * `Couplet` - Pipe the output of this command into the next (`|`)
-/// * `Quiet` - Fork the called process into the background (`&`)
-/// * `And` - Run the next command only if this one succeeds (`&&`)
-/// * `Continue` - String commands together on a single line (`;`)
-/// * `Home` - Interpret `~` as `$HOME`
-/// * `Else` - Any other character
+/// [Rune]s are a way to mark special characters from the input string
+/// (i.e. poetry). Some [Rune]s are special--as they denote the end of a
+/// [Verse][crate::poem::Verse]--and are refered to as a Meter. For
+/// instance, `Addendum`, `Couplet`, `Quiet`, and `And`, are all meters.
+/// Meters also determine how the [Stanza][super::stanza::Stanza] should
+/// be interpreted. For instance, a [Stanza][super::stanza::Stanza] that
+/// is piped needs to have its `STDOUT` captured (rather than printing
+/// out to the terminal), and subsequently sent to the next
+/// [Verse][crate::poem::Verse] in the [Poem][super::super::Poem].
 #[derive(Debug, PartialEq, Eq, Copy, Clone)]
 pub enum Rune {
-    None,        // No meter (the end of a poem)
-    Pause,       // A space
-    Path,        // A forward slash
-    Remark,      // A comment
-    String,      // Interpret the following as one large [Word]
-    Poem,        // Run a sub-poem before the main one
-    Read,        // Read files into STDIN
-    Write,       // Send STDOUT to a file
-    Write2,      // Send STDERR to a file
-    WriteAll,    // Send STDOUT and STDERR to a file
-    Addendum,    // Append STDOUT to a file
-    Addendum2,   // Append STDERR to a file
-    AddendumAll, // Append STDOUT and STDERR to a file
-    Couplet,     // Pipe the output of this command into the next
-    Quiet,       // Fork the command into the background
-    And,         // Run the next command only if this succeeds
-    Continue,    // Run the next command, even if this doesn't succeed
-    Home,        // Interpret '~' as $HOME
-    Else,        // Any other character
+    /// A shell command with no additional actions (the end of a poem)
+    None,
+
+    /// The space character, to dilineate words (`' '`)
+    Pause,
+
+    /// The forward slash character, to dilineate paths (`/`)
+    Path,
+
+    /// Indicates a single line comment (`#`)
+    Remark,
+
+    /// Interpret all characters as one large [Word][super::word::Word]
+    /// (`'` or `"`)
+    String,
+
+    /// A subcommand to run first (`\``)
+    Poem,
+
+    /// Read files into STDIN (`<`)
+    Read,
+
+    /// Write STDOUT to a file (`>`)
+    Write,
+
+    /// Write STDERR to a file (`2>`)
+    Write2,
+
+    /// Write both STDOUT and STDERR to a file (`&>`)
+    WriteAll,
+
+    /// Append STDOUT to a file (`>>`)
+    Addendum,
+
+    /// Append STDERR to a file (`2>>`)
+    Addendum2,
+
+    /// Append both STDOUT and STDERR to a file (`&>>`)
+    AddendumAll,
+
+    /// Pipe the output of this command into the next (`|`)
+    Couplet,
+
+    /// Fork the called process into the background (`&`)
+    Quiet,
+
+    /// Run the next command, only if this one succeeds (`&&`)
+    And,
+
+    /// Run the next command, regardless of whether or not this command
+    /// succeeds (`;` or a newline in a file)
+    Continue,
+
+    /// Interpret `~` as `$HOME`
+    Home,
+
+    /// Any other character
+    Else,
 }
 
 impl fmt::Display for Rune {