Small IR docs, and then some learning about rustdoc.

src/syntax.rs

@@ -1,20 +1,47 @@
+//! NGR Parsing: Reading input, turning it into sense (or errors).
+//! 
+//! This module implement the front end of the compiler, which is responsible for
+//! reading in NGR syntax as a string, turning it into a series of reasonable Rust
+//! structures for us to manipulate, and doing some validation while it's at it.
+//! 
+//! The core flow for this work is:
+//! 
+//!   * Turning the string into a series of language-specific [`Token`]s.
+//!   * Taking those tokens, and computing a basic syntax tree from them,
+//!     using our [`parser`].
+//!   * Validating the tree we have parsed, using the [`validate`] module,
+//!     returning any warnings or errors we have found.
+//!   * Simplifying the tree we have parsed, using the [`simplify`] module,
+//!     into something that's more easily turned into our [compiler internal
+//!     representation](super::ir).
+//! 
+//! In addition to all of this, we make sure that the structures defined in this
+//! module are all:
+//!
+//!   * Instances of [`Pretty`](::pretty::Pretty), so that you can print stuff back
+//!     out that can be read by a human. 
+//!   * Instances of [`Arbitrary`](proptest::prelude::Arbitrary), so they can be
+//!     used in `proptest`-based property testing. There are built-in tests in
+//!     the library, for example, to make sure that the pretty-printing round-trips.
+//!   * Can be evaluated using an `eval` function, for comparison with later
+//!     versions of the function downstream.
 use codespan_reporting::{diagnostic::Diagnostic, files::SimpleFiles};
 use lalrpop_util::lalrpop_mod;
 use logos::Logos;
 
 mod arbitrary;
-pub mod ast;
+mod ast;
 mod eval;
 mod location;
-mod simplify;
+pub mod simplify;
 mod tokens;
 lalrpop_mod!(
     #[allow(clippy::just_underscores_and_digits, clippy::clone_on_copy)]
-    parser,
+    pub parser,
     "/syntax/parser.rs"
 );
 mod pretty;
-mod validate;
+pub mod validate;
 
 pub use crate::syntax::ast::*;
 pub use crate::syntax::location::Location;