feat: multiline ---@return description

emmylua.md

@@ -303,6 +303,7 @@ A function contains multiple tags which form its structure. Like `---@param` for
 ---@param <name> <type> [desc]
 ---@comment
 ---@return <type> [name] [desc]
+---@comment
 ---@see <ref>
 ---@usage `<code>`
 ```
@@ -359,7 +360,8 @@ end
 ---  * {full_build} (boolean) full rebuild or
 ---     incremental build. Defaults to true (full build)
 ---@param reserverd table|nil reserved for the future use
----@return boolean
+---@return boolean _ This is description of return
+---statement that can be expanded to mutliple lines
 function U.multi_line(opts, reserverd)
     print(vim.inspect(opts), vim.inspect(reserverd))
     return true
@@ -426,7 +428,8 @@ U.multi_line({opts}, {reserverd})                                 *U.multi_line*
         {reserverd}  (table|nil)  reserved for the future use
 
     Returns: ~
-        {boolean}
+        {boolean}  This is description of return
+                   statement that can be expanded to mutliple lines
 ```
 
 ### Class

src/parser/tags/func.rs

@@ -31,9 +31,27 @@ parser!(Param, {
 pub struct Return {
     pub ty: String,
     pub name: Option<String>,
-    pub desc: Option<String>,
+    pub desc: Vec<String>,
 }
 
+parser!(Return, {
+    select! {
+        TagType::Return { ty, name, desc } => (ty, name, desc)
+    }
+    .then(select! { TagType::Comment(x) => x }.repeated())
+    .map(|((ty, name, desc), extra)| {
+        let desc = match desc {
+            Some(d) => Vec::from([d])
+                .into_iter()
+                .chain(extra.into_iter())
+                .collect(),
+            None => extra,
+        };
+
+        Self { name, ty, desc }
+    })
+});
+
 #[derive(Debug, Clone)]
 pub struct Func {
     pub name: String,
@@ -52,7 +70,7 @@ parser!(Func, {
     }
     .repeated()
     .then(Param::parse().repeated())
-    .then(select! { TagType::Return { ty, name, desc } => Return { ty, name, desc } }.repeated())
+    .then(Return::parse().repeated())
     .then(See::parse())
     .then(Usage::parse().or_not())
     .then(select! { TagType::Func { prefix, name, kind } => (prefix, name, kind) })
@@ -125,9 +143,9 @@ impl Display for Func {
 
             for param in &self.params {
                 table.add_row([
-                    &format!("{{{}}}", param.name),
-                    &format!("({})", param.ty),
-                    &param.desc.join("\n"),
+                    format!("{{{}}}", param.name),
+                    format!("({})", param.ty),
+                    param.desc.join("\n"),
                 ]);
             }
 
@@ -141,11 +159,12 @@ impl Display for Func {
 
             for entry in &self.returns {
                 table.add_row([
-                    &format!("{{{}}}", entry.ty),
-                    entry
-                        .desc
-                        .as_deref()
-                        .unwrap_or_else(|| entry.name.as_deref().unwrap_or_default()),
+                    format!("{{{}}}", entry.ty),
+                    if entry.desc.is_empty() {
+                        entry.name.clone().unwrap_or_default()
+                    } else {
+                        entry.desc.join("\n")
+                    },
                 ]);
             }
 

tests/basic.rs

@@ -202,6 +202,8 @@ fn functions() {
     ---@param this number
     ---@param that number Second number
     ---@return number
+    ---Some secret number that
+    ---we don't know about
     ---@usage `require('module.U').sub(10, 5)`
     function U.sub(this, that)
         return this - that
@@ -212,6 +214,9 @@ fn functions() {
     ---@param that number Non-magical number #2
     ---@return number _ The magical number #1
     ---@return number _ The magical number #2
+    ---and the fun part is the description can span
+    ---
+    ---over mulitple lines and preserves empty lines
     ---@see U.mul
     ---@see U.sum
     ---@see U.sub
@@ -247,7 +252,8 @@ U.sub({this}, {that})                                                    *U.sub*
         {that}  (number)  Second number
 
     Returns: ~
-        {number}
+        {number}  Some secret number that
+                  we don't know about
 
     Usage: ~
         >
@@ -265,6 +271,9 @@ U.magical({this}, {that})                                            *U.magical*
     Returns: ~
         {number}  The magical number #1
         {number}  The magical number #2
+                  and the fun part is the description can span
+
+                  over mulitple lines and preserves empty lines
 
     See: ~
         |U.mul|