Add some documentation for the reduced AST

schala-lang/language/src/reduced_ast.rs

@@ -1,3 +1,17 @@
+//! # Reduced AST
+//! The reduced AST is a minimal AST designed to be built from the full AST after all possible
+//! static checks have been done. Consequently, the AST reduction phase does very little error
+//! checking itself - any errors should ideally be caught either by an earlier phase, or are
+//! runtime errors that the evaluator should handle. That said, becuase it does do table lookups
+//! that can in principle fail [especially at the moment with most static analysis not yet complete],
+//! there is an Expr variant `ReductionError` to handle these cases.
+//!
+//! A design decision to make - should the ReducedAST types contain all information about
+//! type/layout necessary for the evaluator to work? If so, then the evaluator should not
+//! have access to the symbol table at all and ReducedAST should carry that information. If not,
+//! then ReducedAST shouldn't be duplicating information that can be queried at runtime from the
+//! symbol table. But I think the former might make sense since ultimately the bytecode will be
+//! built from the ReducedAST.
 use std::rc::Rc;
 
 use crate::ast::*;