Add a few doc comments around validation, and fix some typos. (#2154)

Author: erikrose

crates/wasm-encoder/src/component/builder.rs

@@ -134,7 +134,7 @@ impl ComponentBuilder {
     /// Instantiates a core wasm module at `module_index` with the `args`
     /// provided.
     ///
-    /// Returns the index of the core wasm instance crated.
+    /// Returns the index of the core wasm instance created.
     pub fn core_instantiate<'a, A>(&mut self, module_index: u32, args: A) -> u32
     where
         A: IntoIterator<Item = (&'a str, ModuleArg)>,
@@ -146,7 +146,7 @@ impl ComponentBuilder {
 
     /// Creates a new core wasm instance from the `exports` provided.
     ///
-    /// Returns the index of the core wasm instance crated.
+    /// Returns the index of the core wasm instance created.
     pub fn core_instantiate_exports<'a, E>(&mut self, exports: E) -> u32
     where
         E: IntoIterator<Item = (&'a str, ExportKind, u32)>,
@@ -159,7 +159,7 @@ impl ComponentBuilder {
     /// Creates a new aliased item where the core `instance` specified has its
     /// export `name` aliased out with the `kind` specified.
     ///
-    /// Returns the index of the item crated.
+    /// Returns the index of the item created.
     pub fn core_alias_export(&mut self, instance: u32, name: &str, kind: ExportKind) -> u32 {
         self.alias(Alias::CoreInstanceExport {
             instance,

crates/wasm-encoder/src/reencode.rs

@@ -548,7 +548,7 @@ pub enum Error<E = Infallible> {
     InvalidCodeSectionSize,
     /// There was a section that does not belong into a core wasm module.
     UnexpectedNonCoreModuleSection,
-    /// There was a section that does not belong into a compoennt module.
+    /// There was a section that does not belong into a component module.
     UnexpectedNonComponentSection,
     /// A core type definition was found in a component that's not supported.
     UnsupportedCoreTypeInComponent,

crates/wasmparser/src/validator.rs

@@ -346,7 +346,7 @@ pub enum ValidPayload<'a> {
     /// This result indicates that the specified parser should be used instead
     /// of the currently-used parser until this returned one ends.
     Parser(Parser),
-    /// A function was found to be validate.
+    /// A function was found to be validated.
     Func(FuncToValidate<ValidatorResources>, FunctionBody<'a>),
     /// The end payload was validated and the types known to the validator
     /// are provided.

crates/wit-component/src/encoding.rs

@@ -1526,7 +1526,7 @@ impl<'a> EncodingState<'a> {
                 // For import modules that are a "bag of names" iterate over
                 // each name and materialize it into this component with the
                 // `materialize_import` helper. This is then all bottled up into
-                // a bag-of-exports instances which is then used for
+                // a bag-of-exports instance which is then used for
                 // instantiation.
                 ImportInstance::Names(names) => {
                     let mut exports = Vec::new();
@@ -1585,7 +1585,7 @@ impl<'a> EncodingState<'a> {
                 ))
             }
 
-            // Adapters might uset he main module's memory, in which case it
+            // Adapters might use the main module's memory, in which case it
             // should have been previously instantiated.
             Import::MainModuleMemory => {
                 let index = self
@@ -2681,7 +2681,7 @@ pub struct ComponentEncoder {
 impl ComponentEncoder {
     /// Set the core module to encode as a component.
     /// This method will also parse any component type information stored in custom sections
-    /// inside the module, and add them as the interface, imports, and exports.
+    /// inside the module and add them as the interface, imports, and exports.
     /// It will also add any producers information inside the component type information to the
     /// core module.
     pub fn module(mut self, module: &[u8]) -> Result<Self> {

crates/wit-component/src/validation.rs

@@ -181,7 +181,9 @@ impl Hash for PayloadInfo {
 /// The different kinds of items that a module or an adapter can import.
 ///
 /// This is intended to be an exhaustive definition of what can be imported into
-/// core modules within a component that wit-component supports.
+/// core modules within a component that wit-component supports. This doesn't
+/// get down to the level of storing any idx numbers; at its most specific, it
+/// gives a name.
 #[derive(Debug, Clone)]
 pub enum Import {
     /// A top-level world function, with the name provided here, is imported
@@ -449,7 +451,8 @@ impl ImportMap {
         &self.names
     }
 
-    /// Helper function used during validation to build up this `ImportMap`.
+    /// Classify an import and call `insert_import()` on it. Used during
+    /// validation to build up this `ImportMap`.
     fn add(
         &mut self,
         import: wasmparser::Import<'_>,
@@ -469,6 +472,11 @@ impl ImportMap {
         self.insert_import(import, item)
     }
 
+    /// Determines what kind of thing is being imported: maps it from the
+    /// module/name/type triple in the raw wasm module to an enum.
+    ///
+    /// Handles a few special cases, then delegates to
+    /// `classify_component_model_import()`.
     fn classify(
         &self,
         import: wasmparser::Import<'_>,
@@ -980,6 +988,9 @@ impl ImportMap {
         Ok(true)
     }
 
+    /// Map an imported item, by module and field name in `self.names`, to the
+    /// kind of `Import` it is: for example, a certain-typed function from an
+    /// adapter.
     fn insert_import(&mut self, import: wasmparser::Import<'_>, item: Import) -> Result<()> {
         let entry = self
             .names