📜 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/ast.rs

@@ -1,12 +1,32 @@
 use crate::syntax::Location;
 
+/// The set of valid binary operators.
 pub static BINARY_OPERATORS: &[&str] = &["+", "-", "*", "/"];
 
+/// A structure represented a parsed program.
+///
+/// One `Program` is associated with exactly one input file, and the
+/// vector is arranged in exactly the same order as the parsed file.
+/// Because this is the syntax layer, the program is guaranteed to be
+/// syntactically valid, but may be nonsense. There could be attempts
+/// to use unbound variables, for example, until after someone runs
+/// `validate` and it comes back without errors.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Program {
     pub statements: Vec<Statement>,
 }
 
+/// A parsed statement.
+///
+/// Statements are guaranteed to be syntactically valid, but may be
+/// complete nonsense at the semantic level. Which is to say, all the
+/// print statements were correctly formatted, and all the variables
+/// referenced are definitely valid symbols, but they may not have
+/// been defined or anything.
+///
+/// Note that equivalence testing on statements is independent of
+/// source location; it is testing if the two statements say the same
+/// thing, not if they are the exact same statement.
 #[derive(Clone, Debug)]
 pub enum Statement {
     Binding(Location, String, Expression),
@@ -28,6 +48,12 @@ impl PartialEq for Statement {
     }
 }
 
+/// An expression in the underlying syntax.
+///
+/// Like statements, these expressions are guaranteed to have been
+/// formatted correctly, but may not actually make any sense. Also
+/// like Statements, the [`PartialEq`] implementation does not take
+/// source positions into account.
 #[derive(Clone, Debug)]
 pub enum Expression {
     Value(Location, Value),
@@ -54,7 +80,9 @@ impl PartialEq for Expression {
     }
 }
 
+/// A value from the source syntax
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum Value {
+    /// The value of the number, and an optional base that it was written in
     Number(Option<u8>, i64),
 }