From 99983c85e1bd3d3d7e40831942e19049ff432a0e Mon Sep 17 00:00:00 2001
From: magic-akari <akari.ccino@gmail.com>
Date: Tue, 29 Aug 2023 15:59:50 +0800
Subject: [PATCH] fix: Optional JSDoc `@param` (#3577)

---
 CHANGELOG.md                         |  3 +++
 crates/cli-support/src/js/binding.rs | 32 ++++++++++++++++++++++------
 2 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e92134a7331..0862a5d8fd1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -77,6 +77,9 @@
 * Fixed bug allowing JS primitives to be returned from exported constructors.
   [#3562](https://github.com/rustwasm/wasm-bindgen/pull/3562)
 
+* Fixed optional parameters in JSDoc.
+  [#3577](https://github.com/rustwasm/wasm-bindgen/pull/3577)
+
 ## [0.2.87](https://github.com/rustwasm/wasm-bindgen/compare/0.2.86...0.2.87)
 
 Released 2023-06-12.
diff --git a/crates/cli-support/src/js/binding.rs b/crates/cli-support/src/js/binding.rs
index 467220d05ff..1cd3e0f22da 100644
--- a/crates/cli-support/src/js/binding.rs
+++ b/crates/cli-support/src/js/binding.rs
@@ -363,18 +363,36 @@ impl<'a, 'b> Builder<'a, 'b> {
         ts_ret: &Option<String>,
         variadic: bool,
     ) -> String {
-        let mut ret = String::new();
         let (variadic_arg, fn_arg_names) = match arg_names.split_last() {
             Some((last, args)) if variadic => (Some(last), args),
             _ => (None, arg_names),
         };
-        for (name, ty) in fn_arg_names.iter().zip(arg_tys) {
-            ret.push_str("@param {");
-            adapter2ts(ty, &mut ret);
-            ret.push_str("} ");
-            ret.push_str(name);
-            ret.push('\n');
+
+        let mut omittable = true;
+        let mut js_doc_args = Vec::new();
+
+        for (name, ty) in fn_arg_names.iter().zip(arg_tys).rev() {
+            let mut arg = "@param {".to_string();
+
+            adapter2ts(ty, &mut arg);
+            arg.push_str("} ");
+            match ty {
+                AdapterType::Option(..) if omittable => {
+                    arg.push('[');
+                    arg.push_str(name);
+                    arg.push(']');
+                }
+                _ => {
+                    omittable = false;
+                    arg.push_str(name);
+                }
+            }
+            arg.push('\n');
+            js_doc_args.push(arg);
         }
+
+        let mut ret: String = js_doc_args.into_iter().rev().collect();
+
         if let (Some(name), Some(ty)) = (variadic_arg, arg_tys.last()) {
             ret.push_str("@param {...");
             adapter2ts(ty, &mut ret);