docs(tvix/compiler): add a note on use of unwrap/expect for rnix r/4484

Change-Id: I62ca28285685b69d1883afcf18c6068fc2defb5d
Reviewed-on: https://cl.tvl.fyi/c/depot/+/6149
Tested-by: BuildkiteCI
Reviewed-by: grfn <grfn@gws.fyi>
Reviewed-by: sterni <sternenseemann@systemli.org>

1 files changed, 12 insertions, 0 deletions

diff --git a/tvix/eval/src/compiler.rs b/tvix/eval/src/compiler.rs
index 3df0ea4c98..e38b06b456 100644
--- a/tvix/eval/src/compiler.rs
+++ b/tvix/eval/src/compiler.rs
@@ -1,5 +1,17 @@
 //! This module implements a compiler for compiling the rnix AST
 //! representation to Tvix bytecode.
+//!
+//! A note on `unwrap()`: This module contains a lot of calls to
+//! `unwrap()` or `expect(...)` on data structures returned by `rnix`.
+//! The reason for this is that rnix uses the same data structures to
+//! represent broken and correct ASTs, so all typed AST variants have
+//! the ability to represent an incorrect node.
+//!
+//! However, at the time that the AST is passed to the compiler we
+//! have verified that `rnix` considers the code to be correct, so all
+//! variants are filed. In cases where the invariant is guaranteed by
+//! the code in this module, `debug_assert!` has been used to catch
+//! mistakes early during development.
 
 use crate::chunk::Chunk;
 use crate::errors::EvalResult;