📜 Add better documentation across the compiler. (#3)

These changes pay particular attention to API endpoints, to try to
ensure that any rustdocs generated are detailed and sensible. A good
next step, eventually, might be to include doctest examples, as well.
For the moment, it's not clear that they would provide a lot of value,
though.

In addition, this does a couple refactors to simplify the code base in
ways that make things clearer or, at least, briefer.

src/syntax/validate.rs

@@ -2,6 +2,13 @@ use crate::syntax::{Expression, Location, Program, Statement};
 use codespan_reporting::diagnostic::Diagnostic;
 use std::collections::HashMap;
 
+/// An error we found while validating the input program.
+///
+/// These errors indicate that we should stop trying to compile
+/// the program, because it's just fundamentally broken in a way
+/// that we're not going to be able to work through. As with most
+/// of these errors, we recommend converting this to a [`Diagnostic`]
+/// and using [`codespan_reporting`] to present them to the user.
 pub enum Error {
     UnboundVariable(Location, String),
 }
@@ -16,6 +23,13 @@ impl From<Error> for Diagnostic<usize> {
     }
 }
 
+/// A problem we found validating the input that isn't critical.
+///
+/// These are things that the user might want to do something about,
+/// but we can keep going without it being a problem. As with most of
+/// these things, if you want to present this information to the user,
+/// the best way to do so is via [`From`] and [`Diagnostic`], and then
+/// interactions via [`codespan_reporting`].
 #[derive(Debug, PartialEq, Eq)]
 pub enum Warning {
     ShadowedVariable(Location, Location, String),
@@ -37,6 +51,11 @@ impl From<Warning> for Diagnostic<usize> {
 }
 
 impl Program {
+    /// Validate that the program makes semantic sense, not just syntactic sense.
+    ///
+    /// This checks for things like references to variables that don't exist, for
+    /// example, and generates warnings for things that are inadvisable but not
+    /// actually a problem.
     pub fn validate(&self) -> (Vec<Error>, Vec<Warning>) {
         let mut errors = vec![];
         let mut warnings = vec![];
@@ -53,6 +72,15 @@ impl Program {
 }
 
 impl Statement {
+    /// Validate that the statement makes semantic sense, not just syntactic sense.
+    ///
+    /// This checks for things like references to variables that don't exist, for
+    /// example, and generates warnings for things that are inadvisable but not
+    /// actually a problem. Since statements appear in a broader context, you'll
+    /// need to provide the set of variables that are bound where this statement
+    /// occurs. We use a `HashMap` to map these bound locations to the locations
+    /// where their bound, because these locations are handy when generating errors
+    /// and warnings.
     pub fn validate(
         &self,
         bound_variables: &mut HashMap<String, Location>,