Add some top-level documentation.

src/compiler.rs

@@ -9,6 +9,13 @@ use codespan_reporting::{
 use pretty::termcolor::{ColorChoice, StandardStream};
 use target_lexicon::Triple;
 
+/// A high-level compiler for NGR programs.
+/// 
+/// This object can be built once, and then re-used many times to build multiple
+/// files. For most users, the [`Default`] implementation should be sufficient;
+/// it will use `stderr` for warnings and errors, with default colors based on
+/// what we discover from the terminal. For those who want to provide alternate
+/// outputs, though, the `Compiler::new` constructor is available.
 pub struct Compiler {
     file_database: SimpleFiles<String, String>,
     console: StandardStream,
@@ -53,8 +60,19 @@ impl Compiler {
         }
     }
 
-    // This is the actual meat of the compilation chain; we hide it from the user
-    // because the type is kind of unpleasant.
+    /// This is the actual meat of the compilation chain; we hide it from the user
+    /// because the type is kind of unpleasant.
+    /// 
+    /// The weird error type comes from the fact that we can run into three types
+    /// of result:
+    /// 
+    ///    * Fundamental errors, like an incorrectly formatted file or some
+    ///      oddity with IO. These return `Err`.
+    ///    * Validation errors, where we reject the program due to something
+    ///      semantically wrong with them. These return `Ok(None)`.
+    ///    * Success! In this case, we return `Ok(Some(...))`, where the bytes
+    ///      returned is the contents of the compiled object file.
+    /// 
     fn compile_internal(&mut self, input_file: &str) -> Result<Option<Vec<u8>>, CompilerError> {
         // Try to parse the file into our syntax AST. If we fail, emit the error
         // and then immediately return `None`.
@@ -92,6 +110,10 @@ impl Compiler {
         Ok(Some(backend.bytes()?))
     }
 
+    /// Emit a diagnostic.
+    /// 
+    /// This is just a really handy shorthand we use elsewhere in the object, because
+    /// there's a lot of boilerplate we'd like to skip.
     fn emit(&mut self, diagnostic: Diagnostic<usize>) {
         term::emit(
             &mut self.console.lock(),