From 52b24d572522f3bfcd401315942d45beb20ccfa9 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Sun, 29 Nov 2020 18:02:13 -0700
Subject: [PATCH] stage1: add some code comments for ConstValSpecial

---
 src/stage1/all_types.hpp | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/stage1/all_types.hpp b/src/stage1/all_types.hpp
index 957a377b6d..39eec65628 100644
--- a/src/stage1/all_types.hpp
+++ b/src/stage1/all_types.hpp
@@ -338,9 +338,22 @@ struct ConstArgTuple {
 };
 
 enum ConstValSpecial {
+    // The value is only available at runtime. However there may be runtime hints
+    // narrowing the possible values down via the `data.rh_*` fields.
     ConstValSpecialRuntime,
+    // The value is comptime-known and resolved. The `data.x_*` fields can be
+    // accessed.
     ConstValSpecialStatic,
+    // The value is comptime-known to be `undefined`.
     ConstValSpecialUndef,
+    // The value is comptime-known, but not yet resolved. The lazy value system
+    // helps avoid dependency loops by providing answers to certain questions
+    // about values without forcing them to be resolved. For example, the
+    // equation `@sizeOf(Foo) == 0` can be resolved without forcing the struct
+    // layout of `Foo` because we can know whether `Foo` is zero bits without
+    // performing field layout.
+    // A `ZigValue` can be converted from Lazy to Static/Undef by calling the
+    // appropriate resolve function.
     ConstValSpecialLazy,
 };
 
@@ -484,6 +497,8 @@ struct LazyValueErrUnionType {
 
 struct ZigValue {
     ZigType *type;
+    // This field determines how the value is stored. It must be checked
+    // before accessing the `data` union.
     ConstValSpecial special;
     uint32_t llvm_align;
     ConstParent parent;