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, 20 insertions, 13 deletions

diff --git a/src/compose/environment.rs b/src/compose/environment.rs
index 151c7a5..540401b 100644
--- a/src/compose/environment.rs
+++ b/src/compose/environment.rs
@@ -2,19 +2,13 @@ use std::collections::HashMap;
 
 /// Record the shell state
 ///
-/// The [Environment] struct keeps track of various fields, all relating to the
-/// shell state. The environment is the first thing setup at the beginning of
-/// the shell, and is maintained throughout the lifetime of the process.
+/// The [Environment] struct keeps track of various fields, all relating
+/// to the shell state. The environment is the first thing setup at the
+/// beginning of the shell, and is maintained throughout the lifetime of
+/// the process.
 ///
-/// Both [crate::Poem]::read() and [crate::Poem]::recite() rely on this struct
-/// for various functions and features.
-///
-/// # Fields
-/// aliases - A table of aliases, set by the user using the built-in 'alias'
-/// bins - A lookup table for +x files, constructed from the $PATH
-/// cs - Indication of callstack level, helpful for recursively dealing with
-///      aliases
-/// fc - Force the capture of stdout (for internal poems)
+/// Both [read()][crate::poem::read] and [recite()][crate::poem::recite]
+/// rely on this struct for various functions and features.
 ///
 /// # Examples
 /// ```
@@ -22,14 +16,27 @@ use std::collections::HashMap;
 ///     let mut env = compose::env();
 ///     let poem = Poem::read("alias", &mut env)?;
 ///     poem.recite(&mut env)?;
-///     ()
+///     Ok(())
 /// }
 /// ```
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct Environment {
+    /// A table of aliases, set by the user using the built-in 'alias'
+    /// command
     pub aliases: HashMap<String, String>,
+
+    /// A lookup table for +x files, constructed from the $PATH (see
+    /// [spellcheck()][crate::poem::elements::verse::Verse::spellcheck]
+    /// for more details)
     pub bins: Vec<String>,
+
+    /// Indication of callstack level, helpful for recursively dealing
+    /// with aliases (see
+    /// [add()][crate::poem::elements::verse::Verse::add] for more
+    /// details)
     pub cs: u8,
+
+    /// Force the capture of STDOUT (for internal poems)
     pub fc: bool,
 }