[core] Document validation::Interface.

In `wgpu_core::validation`, add documentation for `Interface` and
`EntryPoint`.

Author: jimblandy

wgpu-core/src/validation.rs

@@ -282,18 +282,57 @@ struct EntryPointMeshInfo {
     primitive_topology: wgt::PrimitiveTopology,
 }
 
+/// The [resource interface][ri] of an entry point in a [`naga::Module`].
+///
+/// [ri]: https://www.w3.org/TR/WGSL/#resource-interface
 #[derive(Debug, Default)]
 struct EntryPoint {
+    /// The builtin and local values passed to the entry point.
+    ///
+    /// In WGSL, these can be either passed directly as arguments or
+    /// gathered up in structs that are passed; here, they are all
+    /// flattened out.
     inputs: Vec<Varying>,
+
+    /// The builtin and local values returned by the entry point.
+    ///
+    /// In WGSL, a function either returns a single varying directly,
+    /// or returns a struct of varyings; here, they are all flattened
+    /// out.
     outputs: Vec<Varying>,
+
+    /// All the globals this entry point uses.
+    ///
+    /// Handles here refer to elements of [`Interface::resources`].
     resources: Vec<naga::Handle<Resource>>,
+
     #[allow(unused)]
     spec_constants: Vec<SpecializationConstant>,
+
+    /// Pairs of (sampler, texture) handles that this entry point uses
+    /// together.
+    ///
+    /// This is the same information that Naga provides in
+    /// [`naga::valid::FunctionInfo::sampling_set`] (used for generating GLSL),
+    /// but adjusted to use handles referring to [`Interface::resources`].
     sampling_pairs: FastHashSet<(naga::Handle<Resource>, naga::Handle<Resource>)>,
+
+    /// This entry point's workgroup size, if it is a compute-like shader.
+    ///
+    /// For non-compute-like entry points, this is `[0, 0, 0]`.
     workgroup_size: [u32; 3],
+
+    /// Indicates that the entry point uses dual source blending.
     dual_source_blending: bool,
+
+    /// For task shaders and mesh shaders, the size of the task payload global
+    /// they use to communicate.
     task_payload_size: Option<u32>,
+
+    /// Additional information for mesh shader entry points.
     mesh_info: Option<EntryPointMeshInfo>,
+
+    /// Which slots of immediate data this entry point uses.
     immediate_usage: naga::valid::ImmediateUsage,
 }
 
@@ -309,10 +348,24 @@ impl hashbrown::Equivalent<EntryPointKey> for EntryPointKeyRef<'_> {
     }
 }
 
+/// A summary of the [resource interfaces][ri] of the entry points in a [`naga::Module`].
+///
+/// [ri]: https://www.w3.org/TR/WGSL/#resource-interface
 #[derive(Debug)]
 pub struct Interface {
+    /// A clone of the resource limits of the [`Device`] this module
+    /// was created from.
+    ///
+    /// [`Device`]: crate::device::Device
     limits: wgt::Limits,
+
+    /// All the resources the module cites as global variables.
+    ///
+    /// Specific elements of `entry_points` refer to elements in this
+    /// arena by [`naga::Handle`]`.
     resources: naga::Arena<Resource>,
+
+    /// The resource interface of each [`naga::EntryPoint`] in the module.
     entry_points: FastHashMap<EntryPointKey, EntryPoint>,
 }
 
@@ -1103,6 +1156,19 @@ pub struct StageIo {
 }
 
 impl Interface {
+    /// Build some entry point's list of inputs or outputs.
+    ///
+    /// Given `ty` and `binding` that describe an entry point's
+    /// argument or return value, figure out which builtins or
+    /// locations are involved and add them to `ty`, which is either
+    /// [`EntryPoint::inputs`] or [`EntryPoint::outputs`].
+    ///
+    /// - If `ty` is a struct type, visit its members to find
+    ///   individual bindings, and add them to `list`.
+    ///
+    /// - Otherwise, `binding` must be `Some(b)` where `b` describes a
+    ///   binding's builtin or location, and `ty` gives its type. Add
+    ///   this binding to `list`.
     fn populate(
         list: &mut Vec<Varying>,
         binding: Option<&naga::Binding>,
@@ -1245,6 +1311,11 @@ impl Interface {
         list.push(varying);
     }
 
+    /// Construct an [`Interface`] value describing `module`.
+    ///
+    /// The `info` argument must be the results from validating `module`, and
+    /// `limits` must be the limits for the device that we will use to create
+    /// this shader module.
     pub fn new(module: &naga::Module, info: &naga::valid::ModuleInfo, limits: wgt::Limits) -> Self {
         let mut resources = naga::Arena::new();
         let mut resource_mapping = FastHashMap::default();
@@ -1419,6 +1490,8 @@ impl Interface {
             })
     }
 
+    /// Validate the entry point described by `self` for use with `shader_stage`.
+    ///
     /// Among other things, this implements some validation logic defined by the WebGPU spec. at
     /// <https://www.w3.org/TR/webgpu/#abstract-opdef-validating-inter-stage-interfaces>.
     pub fn check_stage(