From 852e13abbca280b896fd88e722cef7ada11bf3bd Mon Sep 17 00:00:00 2001
From: Rory Dudley
Date: Mon, 20 May 2024 13:56:13 -0600
Subject: Add doc comments for the Environment struct

Added documentation comments for the Environment struct, which includes
uses cases, and defining the fields.
---
 src/compose/environment.rs | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

(limited to 'src/compose/environment.rs')

diff --git a/src/compose/environment.rs b/src/compose/environment.rs
index 7107d57..ea6d070 100644
--- a/src/compose/environment.rs
+++ b/src/compose/environment.rs
@@ -1,5 +1,29 @@
 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.
+///
+/// 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
+///
+/// # Examples
+/// ```
+/// fn main() -> Result<(), io::Error> {
+///     let mut env = compose::env();
+///     let poem = Poem::read("alias", &mut env)?;
+///     poem.recite(&mut env)?;
+///     ()
+/// }
+/// ```
 pub struct Environment {
     pub aliases: HashMap<String, String>,
     pub bins: Vec<String>,
@@ -7,6 +31,7 @@ pub struct Environment {
 }
 
 impl Environment {
+    /// Initialize an [Environment] struct with the default values
     pub fn new() -> Self {
         Environment {
             aliases: HashMap::new(),
-- 
cgit v1.2.3