diff --git a/executable_semantics/ast/README.md b/executable_semantics/ast/README.md index d4558bbced3f..47a61e79d49a 100644 --- a/executable_semantics/ast/README.md +++ b/executable_semantics/ast/README.md @@ -7,6 +7,16 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception The code in this directory defines the AST that represents Carbon code in the rest of `executable-semantics`. +The AST is not quite immutable, because some node properties are set during some +phase of static analysis, rather than during parsing. However, AST mutations are +_monotonic_: once set, a node property cannot be changed. Furthermore, if a +property is set after parsing, its documentation specifies what phase is +responsible for setting it. Certain properties have `has_foo()` members for +querying whether they are set, but those are for internal use within the phase +that sets them. As a result, you can think of the AST as if it were immutable, +but with certain parts that you can't yet observe, depending on what phase of +compilation you're in. + All node types in the AST are derived from [`AstNode`](ast_node.h), and use [LLVM-style RTTI](https://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html) to support safe down-casting and similar operations. Each abstract class `Foo` in the diff --git a/executable_semantics/interpreter/interpreter.h b/executable_semantics/interpreter/interpreter.h index 4d83c93cdcca..d059dfb969f2 100644 --- a/executable_semantics/interpreter/interpreter.h +++ b/executable_semantics/interpreter/interpreter.h @@ -27,12 +27,14 @@ namespace Carbon { auto InterpProgram(const AST& ast, Nonnull arena, bool trace) -> int; // Interprets `e` at compile-time, allocating values on `arena` and -// printing traces if `trace` is true. +// printing traces if `trace` is true. The caller must ensure that all the +// code this evaluates has been typechecked. auto InterpExp(Nonnull e, Nonnull arena, bool trace) -> Nonnull; // Interprets `p` at compile-time, allocating values on `arena` and -// printing traces if `trace` is true. +// printing traces if `trace` is true. The caller must ensure that all the +// code this evaluates has been typechecked. auto InterpPattern(Nonnull p, Nonnull arena, bool trace) -> Nonnull;