From b8982b3be98b22328afe7a376f6932da4c317cc3 Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Fri, 14 Jun 2024 12:30:18 -0700
Subject: [PATCH] Document `AtomicOp` and
 `front::spv::Frontend::lookup_atomic`.

---
 naga/src/front/atomic_upgrade.rs | 14 ++++++++++++++
 naga/src/front/spv/mod.rs        |  4 +++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/naga/src/front/atomic_upgrade.rs b/naga/src/front/atomic_upgrade.rs
index d58eba0dd68..e5d3035dc39 100644
--- a/naga/src/front/atomic_upgrade.rs
+++ b/naga/src/front/atomic_upgrade.rs
@@ -33,6 +33,20 @@ pub(crate) enum AtomicOpInst {
     AtomicIIncrement,
 }
 
+/// Information about some [`Atomic`][as] statement, for upgrading types.
+///
+/// SPIR-V doesn't have atomic types like Naga IR's [`Atomic`][at], it
+/// just has atomic instructions that operate on pointers to ordinary
+/// scalar values, so to build Naga IR from SPIR-V input, we must
+/// observe which variables/arguments/fields the SPIR-V applies atomic
+/// instructions to, and then update their types after the fact.
+///
+/// This type describes some [`Atomic`][as] statement we've generated,
+/// along with enough information for us to find the items whose types
+/// we need to upgrade.
+///
+/// [at]: crate::TypeInner::Atomic
+/// [as]: crate::Statement::Atomic
 #[allow(dead_code)]
 #[derive(Clone, Copy, Debug)]
 pub(crate) struct AtomicOp {
diff --git a/naga/src/front/spv/mod.rs b/naga/src/front/spv/mod.rs
index d14ea784774..b224bd5776a 100644
--- a/naga/src/front/spv/mod.rs
+++ b/naga/src/front/spv/mod.rs
@@ -577,7 +577,9 @@ pub struct Frontend<I> {
     future_member_decor: FastHashMap<(spirv::Word, MemberIndex), Decoration>,
     lookup_member: FastHashMap<(Handle<crate::Type>, MemberIndex), LookupMember>,
     handle_sampling: FastHashMap<Handle<crate::GlobalVariable>, image::SamplingFlags>,
-    // Used to upgrade types used in atomic ops to atomic types, keyed by pointer id
+
+    /// A table of all the [`Atomic`] statements we've generated, so
+    /// we can upgrade the types of their operands.
     lookup_atomic: FastHashMap<spirv::Word, atomic_upgrade::AtomicOp>,
     lookup_type: FastHashMap<spirv::Word, LookupType>,
     lookup_void_type: Option<spirv::Word>,