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, 15 insertions, 0 deletions

diff --git a/src/compose.rs b/src/compose.rs
index dfbbaef..b12d1a4 100644
--- a/src/compose.rs
+++ b/src/compose.rs
@@ -5,6 +5,14 @@ use std::env;
 use std::fs;
 use std::path::PathBuf;
 
+/// Setup the global shell environment
+///
+/// Sets up the shell's environment via configuration files. In order:
+/// * `/etc/dwvshrc`
+/// * `~/.dwvshrc`
+///
+/// For debug builds, all files will instead be sourced from
+/// `./dist/...` with the exception of `~/.dwvshrc`.
 pub fn env() -> Environment {
     // Create a new Environment object, to store some extra shell info
     let mut env = Environment::new();
@@ -39,6 +47,13 @@ pub fn env() -> Environment {
     env
 }
 
+/// Read, read, and recite
+///
+/// Small, reusable function used to do the heavy lifting in regards to
+/// sourcing configuration files. [Read][fs::read_to_string]s a file
+/// from disk, then [read][crate::poem::read]s (parses) a [Poem],
+/// then [recite][crate::poem::recite]s that [Poem].
+/// Configuration files are just shell scripts.
 fn rrr(path: PathBuf, env: &mut Environment) {
     let poetry = match fs::read_to_string(&path) {
         Ok(poetry) => poetry,