wit-component, wit-parser: preserve doc comments through embed path

Author: Mees-Molenaar

crates/wit-component/src/metadata.rs

@@ -50,7 +50,9 @@ use wasm_encoder::{
 };
 use wasm_metadata::Producers;
 use wasmparser::{BinaryReader, Encoding, Parser, Payload};
-use wit_parser::{CloneMaps, Package, PackageName, Resolve, World, WorldId, WorldItem, WorldKey};
+use wit_parser::{
+    CloneMaps, Package, PackageMetadata, PackageName, Resolve, World, WorldId, WorldItem, WorldKey,
+};
 
 const CURRENT_VERSION: u8 = 0x04;
 const CUSTOM_SECTION_NAME: &str = "wit-component-encoding";
@@ -292,6 +294,12 @@ pub fn encode(
         data: Cow::Borrowed(&[CURRENT_VERSION, string_encoding]),
     });
 
+    let package_docs = PackageMetadata::extract(resolve, world.package.unwrap());
+    builder.custom_section(&CustomSection {
+        name: PackageMetadata::SECTION_NAME.into(),
+        data: package_docs.encode()?.into(),
+    });
+
     let ty = builder.type_component(None, &outer_ty);
     builder.export(&world.name, ComponentExportKind::Type, ty, None);
 

crates/wit-parser/src/decoding.rs

@@ -429,6 +429,8 @@ pub fn decode_world(wasm: &[u8]) -> Result<(Resolve, WorldId)> {
     let mut exports = Vec::new();
     let mut depth = 1;
     let mut types = None;
+    #[cfg(feature = "serde")]
+    let mut package_metadata: Option<PackageMetadata> = None;
 
     for payload in Parser::new(0).parse_all(wasm) {
         let payload = payload?;
@@ -451,6 +453,15 @@ pub fn decode_world(wasm: &[u8]) -> Result<(Resolve, WorldId)> {
                     exports.push(export?);
                 }
             }
+            #[cfg(feature = "serde")]
+            Payload::CustomSection(s)
+                if depth == 1 && s.name() == PackageMetadata::SECTION_NAME =>
+            {
+                if package_metadata.is_some() {
+                    bail!("multiple {:?} sections", PackageMetadata::SECTION_NAME);
+                }
+                package_metadata = Some(PackageMetadata::decode(s.data())?);
+            }
             _ => {}
         }
     }
@@ -489,12 +500,16 @@ pub fn decode_world(wasm: &[u8]) -> Result<(Resolve, WorldId)> {
             worlds: &mut worlds,
         },
     )?;
-    let (resolve, pkg) = decoder.finish(Package {
+    let (mut resolve, pkg) = decoder.finish(Package {
         name,
         interfaces,
         worlds,
         docs: Default::default(),
     });
+    #[cfg(feature = "serde")]
+    if let Some(metadata) = package_metadata {
+        metadata.inject(&mut resolve, pkg)?;
+    }
     // The package decoded here should only have a single world so extract that
     // here to return.
     let world = *resolve.packages[pkg].worlds.iter().next().unwrap().1;

tests/cli/component-embed-only-custom.wit.stdout

@@ -1,5 +1,6 @@
 (component
   (@custom "wit-component-encoding" "/04/00")
+  (@custom "package-docs" "/01{/22docs/22:/22RUN: component embed --only-custom -w foo % | print/22}")
   (type (;0;)
     (component
       (type (;0;)

tests/cli/component-embed-preserves-docs.wit

@@ -0,0 +1,17 @@
+// RUN: component embed --dummy % | component wit
+
+package foo:docs-test;
+
+/// The interface.
+interface my-interface {
+  /// The function.
+  my-func: func(
+    /// The function's argument.
+    my-arg: string,
+  ) -> string;
+}
+
+/// A world with documentation.
+world my-world {
+  export my-interface;
+}

tests/cli/component-embed-preserves-docs.wit.stdout

@@ -0,0 +1,17 @@
+package root:root;
+
+world root {
+  export foo:docs-test/my-interface;
+}
+/// RUN: component embed --dummy % | component wit
+package foo:docs-test {
+  /// The interface.
+  interface my-interface {
+    /// The function.
+    my-func: func(my-arg: string) -> string;
+  }
+  /// A world with documentation.
+  world my-world {
+    export my-interface;
+  }
+}

tests/cli/component-wit-of-core-module.wit.stdout

@@ -5,6 +5,7 @@ world root {
 
   export y: func();
 }
+/// RUN: component embed --dummy % | component wit
 package a:b {
   world foo {
     import x: func();

tests/cli/importize.wit.simple-component.stdout

@@ -3,6 +3,16 @@ package root:root;
 world root-importized {
   import importize:importize/t;
 }
+/// RUN[simple]: component wit --importize-world simple %
+/// RUN[simple-rename]: component wit --importize-world simple-rename --importize-out-world-name test-rename  %
+/// RUN[simple-component]: component embed --dummy --world simple % | /
+///                        component wit --importize
+/// RUN[with-deps]: component wit --importize-world with-deps %
+/// RUN[simple-toplevel]: component wit --importize-world simple-toplevel %
+/// RUN[toplevel-deps]: component wit --importize-world toplevel-deps %
+/// FAIL[fail1]: component wit --importize-world fail1 %
+/// RUN[trim-imports]: component wit --importize-world trim-imports %
+/// RUN[tricky-import]: component wit --importize-world tricky-import %
 package importize:importize {
   interface t {
     resource r;

tests/cli/multiple-packages-one-world.wit.stdout

@@ -19,6 +19,7 @@ package test:foo2 {
 }
 
 
+/// RUN: component embed --dummy --wat % | component wit
 package foo:root {
   world hello {
     import test:foo1/bar;

tests/cli/print-core-wasm-wit.wit.stdout

@@ -3,6 +3,7 @@ package root:root;
 world root {
   import foo:foo/my-interface;
 }
+/// RUN: component embed --dummy % | component wit
 package foo:foo {
   interface my-interface {
     foo: func();

tests/cli/reparent-anonymous-interfaces-on-merge.wit.stdout

@@ -11,6 +11,11 @@ world root {
   export b: interface {
   }
 }
+/// RUN: component embed --dummy --world w1 % | /
+///      component embed         --world w2 % | /
+///      component embed         --world w3 % | /
+///      component embed         --world w4 % | /
+///      component wit
 package a:b {
   world w1 {
   }