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

diff --git a/src/poem/elements/verse/logic.rs b/src/poem/elements/verse/logic.rs
index f5efdee..e7ed4df 100644
--- a/src/poem/elements/verse/logic.rs
+++ b/src/poem/elements/verse/logic.rs
@@ -1,3 +1,17 @@
+/// Spawn a program
+///
+/// This macro provides a common interface for running system programs,
+/// as well as built-in shell commands. This is possible, since the
+/// shell's homebrew facilities for running built-ins mimic the
+/// interface of [std::process::Command]. See
+/// [crate::poem::anthology::Anthology] for the implementation details.
+///
+/// First, the macro sets the arguments for the command. Next, it
+/// determines the whether or not text should be piped in/out of the
+/// command. The process is spawned, then it determines what to do based
+/// on the [crate::poem::elements::verse::Verse]'s meter (wait, fork to
+/// background, or capture STDOUT). Finally, the macro performs any IO
+/// functions (i.e. writing/appending STDOUT or STDERR to a file).
 #[macro_export]
 macro_rules! incant {
     ($verb:expr, $command:expr, $out:expr, $pids:expr, $env:expr, $self:expr) => {{