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

@@ -2,8 +2,27 @@ use crate::backend::runtime::RuntimeFunctionError;
 use codespan_reporting::diagnostic::Diagnostic;
 use cranelift_codegen::{isa::LookupError, settings::SetError, CodegenError};
 use cranelift_module::ModuleError;
+use internment::ArcIntern;
 use thiserror::Error;
 
+/// An error in the translation to a backend (either the JIT or the static compiler).
+///
+/// In general, this is just a nice summary error type for a bunch of downstream
+/// errors; the exception are internal errors from builtin functions or variable
+/// lookups.
+///
+/// Unlike some other errors in the system, the translation to a `Diagnostic` does
+/// not necessarily provide a whole lot of value, because we have lost most of the
+/// source information by the time we're generating these errors. That being said,
+/// people who want to provide nicer error messages might consider using the
+/// translation through `Diagnostic` anyways, just in case we add more information
+/// in the future.
+///
+/// Finally, the `PartialEq` for this function is a bit fuzzy. In some cases, it
+/// ensures that the errors match exactly. In other cases, though, it just checks to
+/// see if the two errors are of the same class; e.g., it will return true if both
+/// errors are `BackendError::CodegenError`, regardless of what the specific
+/// `CodegenError` is.
 #[derive(Debug, Error)]
 pub enum BackendError {
     #[error("Cranelift module error: {0}")]
@@ -11,7 +30,7 @@ pub enum BackendError {
     #[error("Builtin function error: {0}")]
     BuiltinError(#[from] RuntimeFunctionError),
     #[error("Internal variable lookup error")]
-    VariableLookupFailure,
+    VariableLookupFailure(ArcIntern<String>),
     #[error(transparent)]
     CodegenError(#[from] CodegenError),
     #[error(transparent)]
@@ -31,9 +50,8 @@ impl From<BackendError> for Diagnostic<usize> {
             BackendError::BuiltinError(me) => {
                 Diagnostic::error().with_message(format!("Internal runtime function error: {}", me))
             }
-            BackendError::VariableLookupFailure => {
-                Diagnostic::error().with_message("Internal variable lookup error!")
-            }
+            BackendError::VariableLookupFailure(x) => Diagnostic::error()
+                .with_message(format!("Internal variable lookup error for {}", x)),
             BackendError::CodegenError(me) => {
                 Diagnostic::error().with_message(format!("Internal codegen error: {}", me))
             }
@@ -58,8 +76,12 @@ impl PartialEq for BackendError {
                 _ => false,
             },
 
+            // because the underlying `CodegenError` doesn't implement `PartialEq',
+            // we just check that they're both `CodegenError`s.
             BackendError::CodegenError(_) => matches!(other, BackendError::CodegenError(_)),
 
+            // because the underlying `ModuleError` doesn't implement `PartialEq',
+            // we just check that they're both `Cranelift`s.
             BackendError::Cranelift(_) => matches!(other, BackendError::Cranelift(_)),
 
             BackendError::LookupError(a) => match other {
@@ -72,7 +94,10 @@ impl PartialEq for BackendError {
                 _ => false,
             },
 
-            BackendError::VariableLookupFailure => other == &BackendError::VariableLookupFailure,
+            BackendError::VariableLookupFailure(a) => match other {
+                BackendError::VariableLookupFailure(b) => a == b,
+                _ => false,
+            },
 
             BackendError::Write(a) => match other {
                 BackendError::Write(b) => a == b,