Document AtomicOp and front::spv::Frontend::lookup_atomic.

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 {

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>,