Add JSDoc type annotations to C-style enums (#4157)

Author: RunDevelopment

CHANGELOG.md

@@ -11,6 +11,9 @@
 * Added bindings for [MathMLElement](https://www.w3.org/TR/MathML3).
   [#4143](https://github.com/rustwasm/wasm-bindgen/pull/4143)
 
+* Added JSDoc type annotations to C-style enums.
+  [#4192](https://github.com/rustwasm/wasm-bindgen/pull/4192)
+
 ### Changed
 
 * String enums now generate private TypeScript types but only if used.

crates/cli-support/src/js/mod.rs

@@ -3773,11 +3773,11 @@ __wbg_set_wasm(wasm);"
     }
 
     fn generate_enum(&mut self, enum_: &AuxEnum) -> Result<(), Error> {
-        let docs = format_doc_comments(&enum_.comments, None);
         let mut variants = String::new();
 
         if enum_.generate_typescript {
-            self.typescript.push_str(&docs);
+            self.typescript
+                .push_str(&format_doc_comments(&enum_.comments, None));
             self.typescript
                 .push_str(&format!("export enum {} {{", enum_.name));
         }
@@ -3808,6 +3808,18 @@ __wbg_set_wasm(wasm);"
         if enum_.generate_typescript {
             self.typescript.push_str("\n}\n");
         }
+
+        // add an `@enum {1 | 2 | 3}` to ensure that enums type-check even without .d.ts
+        let mut at_enum = "@enum {".to_string();
+        for (i, (_, value, _)) in enum_.variants.iter().enumerate() {
+            if i != 0 {
+                at_enum.push_str(" | ");
+            }
+            at_enum.push_str(&value.to_string());
+        }
+        at_enum.push('}');
+        let docs = format_doc_comments(&enum_.comments, Some(at_enum));
+
         self.export(
             &enum_.name,
             &format!("Object.freeze({{ {} }})", variants),
@@ -3830,18 +3842,17 @@ __wbg_set_wasm(wasm);"
                 .contains(&TsReference::StringEnum(string_enum.name.clone()))
         {
             let docs = format_doc_comments(&string_enum.comments, None);
+            let type_expr = if variants.is_empty() {
+                "never".to_string()
+            } else {
+                variants.join(" | ")
+            };
 
             self.typescript.push_str(&docs);
             self.typescript.push_str("type ");
             self.typescript.push_str(&string_enum.name);
             self.typescript.push_str(" = ");
-
-            if variants.is_empty() {
-                self.typescript.push_str("never");
-            } else {
-                self.typescript.push_str(&variants.join(" | "));
-            }
-
+            self.typescript.push_str(&type_expr);
             self.typescript.push_str(";\n");
         }
 

crates/cli/tests/reference/enums.js

@@ -64,6 +64,7 @@ export function option_string_enum_echo(color) {
 
 /**
  * A color.
+ * @enum {0 | 1 | 2}
  */
 export const Color = Object.freeze({
 /**
@@ -78,7 +79,9 @@ Yellow:1,"1":"Yellow",
  * Red as a rose.
  */
 Red:2,"2":"Red", });
-
+/**
+ * @enum {0 | 1 | 42 | 43}
+ */
 export const ImplicitDiscriminant = Object.freeze({ A:0,"0":"A",B:1,"1":"B",C:42,"42":"C",D:43,"43":"D", });
 
 const __wbindgen_enum_ColorName = ["green", "yellow", "red"];