From 8aae069f22ac94ec46329a9adbfaf341cd3e7adf Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Tue, 7 Sep 2021 11:14:42 -0700
Subject: [PATCH] Document some Expression, EntryPoint, and Module rules.

---
 src/lib.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 1ee273e58c..97af89d3fa 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1451,6 +1451,9 @@ pub struct Function {
     /// Local variables defined and used in the function.
     pub local_variables: Arena<LocalVariable>,
     /// Expressions used inside this function.
+    ///
+    /// An `Expression` must occur before all other `Expression`s that use its
+    /// value.
     pub expressions: Arena<Expression>,
     /// Map of expressions that have associated variable names
     pub named_expressions: NamedExpressions,
@@ -1503,6 +1506,8 @@ pub struct Function {
 #[cfg_attr(feature = "deserialize", derive(Deserialize))]
 pub struct EntryPoint {
     /// Name of this entry point, visible externally.
+    ///
+    /// Entry point names for a given `stage` must be distinct within a module.
     pub name: String,
     /// Shader stage.
     pub stage: ShaderStage,
@@ -1536,6 +1541,9 @@ pub struct Module {
     /// Storage for the global variables defined in this module.
     pub global_variables: Arena<GlobalVariable>,
     /// Storage for the functions defined in this module.
+    ///
+    /// Each function must appear in this arena strictly before all its callers.
+    /// Recursion is not supported.
     pub functions: Arena<Function>,
     /// Entry points.
     pub entry_points: Vec<EntryPoint>,