Include docs in imports and exports. (#960)

Include the parsed documentation comment in the AST's `Import` and `Export`
records so that, for example, documentation for the following function
can be included in the generated bindings.

```
default world component {
    /// Say hello!
    export hello-world: func() -> string
}
```

This will make the documentation generated by `cargo-component doc`
added in bytecodealliance/cargo-component#63 more useful, and will
allow me to fix a bug in a test which is supposed to be testing that the
documentation comments show up.

Author: sunfishcode

crates/wit-parser/src/ast.rs

@@ -150,8 +150,8 @@ pub enum WorldItem<'a> {
 impl<'a> WorldItem<'a> {
     fn parse(tokens: &mut Tokenizer<'a>, docs: Docs<'a>) -> Result<WorldItem<'a>> {
         match tokens.clone().next()? {
-            Some((_span, Token::Import)) => Import::parse(tokens).map(WorldItem::Import),
-            Some((_span, Token::Export)) => Export::parse(tokens).map(WorldItem::Export),
+            Some((_span, Token::Import)) => Import::parse(tokens, docs).map(WorldItem::Import),
+            Some((_span, Token::Export)) => Export::parse(tokens, docs).map(WorldItem::Export),
             Some((_span, Token::Use)) => Use::parse(tokens).map(WorldItem::Use),
             Some((_span, Token::Type)) => TypeDef::parse(tokens, docs).map(WorldItem::Type),
             Some((_span, Token::Flags)) => TypeDef::parse_flags(tokens, docs).map(WorldItem::Type),
@@ -174,32 +174,34 @@ impl<'a> WorldItem<'a> {
 }
 
 pub struct Import<'a> {
+    docs: Docs<'a>,
     name: Id<'a>,
     kind: ExternKind<'a>,
 }
 
 impl<'a> Import<'a> {
-    fn parse(tokens: &mut Tokenizer<'a>) -> Result<Import<'a>> {
+    fn parse(tokens: &mut Tokenizer<'a>, docs: Docs<'a>) -> Result<Import<'a>> {
         tokens.expect(Token::Import)?;
         let name = parse_id(tokens)?;
         tokens.expect(Token::Colon)?;
         let kind = ExternKind::parse(tokens)?;
-        Ok(Import { name, kind })
+        Ok(Import { docs, name, kind })
     }
 }
 
 pub struct Export<'a> {
+    docs: Docs<'a>,
     name: Id<'a>,
     kind: ExternKind<'a>,
 }
 
 impl<'a> Export<'a> {
-    fn parse(tokens: &mut Tokenizer<'a>) -> Result<Export<'a>> {
+    fn parse(tokens: &mut Tokenizer<'a>, docs: Docs<'a>) -> Result<Export<'a>> {
         tokens.expect(Token::Export)?;
         let name = parse_id(tokens)?;
         tokens.expect(Token::Colon)?;
         let kind = ExternKind::parse(tokens)?;
-        Ok(Export { name, kind })
+        Ok(Export { docs, name, kind })
     }
 }
 

crates/wit-parser/src/ast/resolve.rs

@@ -432,18 +432,20 @@ impl<'a> Resolver<'a> {
         let mut imported_interfaces = HashMap::new();
         let mut exported_interfaces = HashMap::new();
         for item in world.items.iter() {
-            let (name, kind, desc, spans, interfaces) = match item {
+            let (docs, name, kind, desc, spans, interfaces) = match item {
                 // handled in `resolve_types`
                 ast::WorldItem::Use(_) | ast::WorldItem::Type(_) => continue,
 
                 ast::WorldItem::Import(import) => (
+                    &import.docs,
                     &import.name,
                     &import.kind,
                     "import",
                     &mut import_spans,
                     &mut imported_interfaces,
                 ),
                 ast::WorldItem::Export(export) => (
+                    &export.docs,
                     &export.name,
                     &export.kind,
                     "export",
@@ -462,7 +464,7 @@ impl<'a> Resolver<'a> {
                 }
                 .into());
             }
-            let world_item = self.resolve_world_item(name.name, document, kind)?;
+            let world_item = self.resolve_world_item(docs, name.name, document, kind)?;
             if let WorldItem::Interface(id) = world_item {
                 if interfaces.insert(id, name.name).is_some() {
                     return Err(Error {
@@ -492,14 +494,15 @@ impl<'a> Resolver<'a> {
 
     fn resolve_world_item(
         &mut self,
+        docs: &ast::Docs<'a>,
         name: &str,
         document: DocumentId,
         kind: &ast::ExternKind<'a>,
     ) -> Result<WorldItem> {
         match kind {
             ast::ExternKind::Interface(_span, items) => {
                 let prev = mem::take(&mut self.type_lookup);
-                let id = self.resolve_interface(document, None, items, &Default::default())?;
+                let id = self.resolve_interface(document, None, items, docs)?;
                 self.type_lookup = prev;
                 Ok(WorldItem::Interface(id))
             }
@@ -508,7 +511,7 @@ impl<'a> Resolver<'a> {
                 Ok(WorldItem::Interface(id))
             }
             ast::ExternKind::Func(func) => {
-                let func = self.resolve_function(Docs::default(), name, func)?;
+                let func = self.resolve_function(docs, name, func)?;
                 Ok(WorldItem::Function(func))
             }
         }
@@ -519,7 +522,7 @@ impl<'a> Resolver<'a> {
         document: DocumentId,
         name: Option<&'a str>,
         fields: &[ast::InterfaceItem<'a>],
-        docs: &super::Docs<'a>,
+        docs: &ast::Docs<'a>,
     ) -> Result<InterfaceId> {
         let docs = self.docs(docs);
         let interface_id = self.interfaces.alloc(Interface {
@@ -558,19 +561,16 @@ impl<'a> Resolver<'a> {
         // defined.
         for field in fields {
             match field {
-                ast::InterfaceItem::Value(value) => {
-                    let docs = self.docs(&value.docs);
-                    match &value.kind {
-                        ValueKind::Func(func) => {
-                            self.define_interface_name(&value.name, TypeOrItem::Item("function"))?;
-                            let func = self.resolve_function(docs, value.name.name, func)?;
-                            let prev = self.interfaces[interface_id]
-                                .functions
-                                .insert(value.name.name.to_string(), func);
-                            assert!(prev.is_none());
-                        }
+                ast::InterfaceItem::Value(value) => match &value.kind {
+                    ValueKind::Func(func) => {
+                        self.define_interface_name(&value.name, TypeOrItem::Item("function"))?;
+                        let func = self.resolve_function(&value.docs, value.name.name, func)?;
+                        let prev = self.interfaces[interface_id]
+                            .functions
+                            .insert(value.name.name.to_string(), func);
+                        assert!(prev.is_none());
                     }
-                }
+                },
                 ast::InterfaceItem::Use(_) | ast::InterfaceItem::TypeDef(_) => {}
             }
         }
@@ -680,7 +680,13 @@ impl<'a> Resolver<'a> {
         Ok(())
     }
 
-    fn resolve_function(&mut self, docs: Docs, name: &str, func: &ast::Func) -> Result<Function> {
+    fn resolve_function(
+        &mut self,
+        docs: &ast::Docs<'_>,
+        name: &str,
+        func: &ast::Func,
+    ) -> Result<Function> {
+        let docs = self.docs(docs);
         let params = self.resolve_params(&func.params)?;
         let results = self.resolve_results(&func.results)?;
         Ok(Function {