feat(sema): lower natspec

crates/ast/src/ast/mod.rs

@@ -119,7 +119,18 @@ impl fmt::Debug for DocComments<'_> {
     }
 }
 
-impl DocComments<'_> {
+impl<'ast> DocComments<'ast> {
+    /// Returns a reference to the empty documentation comments.
+    pub fn empty() -> &'static Self {
+        // SAFETY: we're just changing the type wrapper, not the underlying data (which is empty).
+        unsafe {
+            std::mem::transmute::<
+                &'static ThinSlice<DocComment<'static>>,
+                &'static DocComments<'static>,
+            >(<&ThinSlice<DocComment<'static>>>::default())
+        }
+    }
+
     /// Returns the span containing all doc-comments.
     pub fn span(&self) -> Span {
         Span::join_first_last(self.iter().map(|d| d.span))

crates/ast/src/ast/natspec.rs

@@ -70,8 +70,8 @@ pub enum NatSpecKind {
     Param { name: Ident },
     /// `@return <name>`
     ///
-    /// Documents a return variable. The `name` field contains the return variable name.
-    Return { name: Ident },
+    /// Documents a return variable. The optional `name` field contains the return variable name.
+    Return { name: Option<Ident> },
     /// `@inheritdoc <contract>`
     ///
     /// Copies all tags from the base function. The `contract` field contains the contract name.

crates/parse/src/parser/mod.rs

@@ -1111,7 +1111,9 @@ fn parse_natspec(
                     let ident = Ident::new(Symbol::intern(name), comment_span);
                     match tag {
                         "param" => ast::NatSpecKind::Param { name: ident },
-                        "return" => ast::NatSpecKind::Return { name: ident },
+                        "return" => ast::NatSpecKind::Return {
+                            name: if content_start_pos == line_end { None } else { Some(ident) },
+                        },
                         "inheritdoc" => ast::NatSpecKind::Inheritdoc { contract: ident },
                         _ => unreachable!(),
                     }
@@ -1187,7 +1189,9 @@ mod tests {
             ast::NatSpecKind::Notice if kind == "notice" => None,
             ast::NatSpecKind::Dev if kind == "dev" => None,
             ast::NatSpecKind::Param { name } if kind == "param" => Some(name.name.as_str()),
-            ast::NatSpecKind::Return { name } if kind == "return" => Some(name.name.as_str()),
+            ast::NatSpecKind::Return { name } if kind == "return" => {
+                name.as_ref().map(|n| n.name.as_str())
+            }
             ast::NatSpecKind::Inheritdoc { contract } if kind == "inheritdoc" => {
                 Some(contract.name.as_str())
             }