Improved doc comment formatting

CHANGELOG.md

@@ -64,6 +64,9 @@
 * Fixed enum variant name collisions with object prototype fields.
   [#4137](https://github.com/rustwasm/wasm-bindgen/pull/4137)
 
+* Fixed multiline doc comment alignment and remove empty ones entirely.
+  [#4135](https://github.com/rustwasm/wasm-bindgen/pull/4135)
+
 --------------------------------------------------------------------------------
 
 ## [0.2.93](https://github.com/rustwasm/wasm-bindgen/compare/0.2.92...0.2.93)

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

@@ -4126,18 +4126,23 @@ fn check_duplicated_getter_and_setter_names(
 
 fn format_doc_comments(comments: &str, js_doc_comments: Option<String>) -> String {
     let body: String = comments.lines().fold(String::new(), |mut output, c| {
-        let _ = writeln!(output, "*{}", c);
+        let _ = writeln!(output, " *{}", c);
         output
     });
     let doc = if let Some(docs) = js_doc_comments {
         docs.lines().fold(String::new(), |mut output: String, l| {
-            let _ = writeln!(output, "* {}", l);
+            let _ = writeln!(output, " * {}", l);
             output
         })
     } else {
         String::new()
     };
-    format!("/**\n{}{}*/\n", body, doc)
+    if body.is_empty() && doc.is_empty() {
+        // don't emit empty doc comments
+        String::new()
+    } else {
+        format!("/**\n{}{} */\n", body, doc)
+    }
 }
 
 fn require_class<'a>(
@@ -4222,7 +4227,13 @@ impl ExportedClass {
         self.contents.push_str(js);
         self.contents.push('\n');
         if let Some(ts) = ts {
-            self.typescript.push_str(docs);
+            if !docs.is_empty() {
+                for line in docs.lines() {
+                    self.typescript.push_str("  ");
+                    self.typescript.push_str(line);
+                    self.typescript.push('\n');
+                }
+            }
             self.typescript.push_str("  ");
             self.typescript.push_str(function_prefix);
             self.typescript.push_str(function_name);

crates/cli-support/src/lib.rs

@@ -492,9 +492,13 @@ fn reset_indentation(s: &str) -> String {
     let mut indent: u32 = 0;
     let mut dst = String::new();
 
+    fn is_doc_comment(line: &str) -> bool {
+        line.starts_with("*")
+    }
+
     for line in s.lines() {
         let line = line.trim();
-        if line.starts_with('}') || (line.ends_with('}') && !line.starts_with('*')) {
+        if line.starts_with('}') || (line.ends_with('}') && !is_doc_comment(line)) {
             indent = indent.saturating_sub(1);
         }
         let extra = if line.starts_with(':') || line.starts_with('?') {
@@ -506,11 +510,14 @@ fn reset_indentation(s: &str) -> String {
             for _ in 0..indent + extra {
                 dst.push_str("    ");
             }
+            if is_doc_comment(line) {
+                dst.push(' ');
+            }
             dst.push_str(line);
         }
         dst.push('\n');
         // Ignore { inside of comments and if it's an exported enum
-        if line.ends_with('{') && !line.starts_with('*') && !line.ends_with("Object.freeze({") {
+        if line.ends_with('{') && !is_doc_comment(line) && !line.ends_with("Object.freeze({") {
             indent += 1;
         }
     }

crates/cli/tests/reference/add.d.ts

@@ -1,14 +1,14 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
-* @param {number} a
-* @param {number} b
-* @returns {number}
-*/
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
 export function add_u32(a: number, b: number): number;
 /**
-* @param {number} a
-* @param {number} b
-* @returns {number}
-*/
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
 export function add_i32(a: number, b: number): number;

crates/cli/tests/reference/add.js

@@ -4,20 +4,20 @@ export function __wbg_set_wasm(val) {
 }
 
 /**
-* @param {number} a
-* @param {number} b
-* @returns {number}
-*/
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
 export function add_u32(a, b) {
     const ret = wasm.add_u32(a, b);
     return ret >>> 0;
 }
 
 /**
-* @param {number} a
-* @param {number} b
-* @returns {number}
-*/
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
 export function add_i32(a, b) {
     const ret = wasm.add_i32(a, b);
     return ret;

crates/cli/tests/reference/anyref-import-catch.d.ts

@@ -1,5 +1,3 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
-*/
 export function exported(): void;

crates/cli/tests/reference/anyref-import-catch.js

@@ -53,8 +53,7 @@ function takeFromExternrefTable0(idx) {
     wasm.__externref_table_dealloc(idx);
     return value;
 }
-/**
-*/
+
 export function exported() {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);

crates/cli/tests/reference/anyref-nop.d.ts

@@ -1,5 +1,3 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
-*/
 export function foo(): void;

crates/cli/tests/reference/anyref-nop.js

@@ -3,8 +3,7 @@ export function __wbg_set_wasm(val) {
     wasm = val;
 }
 
-/**
-*/
+
 export function foo() {
     wasm.foo();
 }

crates/cli/tests/reference/async-number.d.ts

@@ -1,6 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
-* @returns {Promise<number>}
-*/
+ * @returns {Promise<number>}
+ */
 export function foo(): Promise<number>;

crates/cli/tests/reference/async-void.d.ts

@@ -1,6 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
-* @returns {Promise<void>}
-*/
+ * @returns {Promise<void>}
+ */
 export function foo(): Promise<void>;

crates/cli/tests/reference/builder.d.ts

@@ -1,11 +1,9 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
-*/
 export class ClassBuilder {
   free(): void;
-/**
-* @returns {ClassBuilder}
-*/
+  /**
+   * @returns {ClassBuilder}
+   */
   static builder(): ClassBuilder;
 }

crates/cli/tests/reference/builder.js

@@ -27,8 +27,7 @@ function getStringFromWasm0(ptr, len) {
 const ClassBuilderFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_classbuilder_free(ptr >>> 0, 1));
-/**
-*/
+
 export class ClassBuilder {
 
     static __wrap(ptr) {
@@ -51,8 +50,8 @@ export class ClassBuilder {
         wasm.__wbg_classbuilder_free(ptr, 0);
     }
     /**
-    * @returns {ClassBuilder}
-    */
+     * @returns {ClassBuilder}
+     */
     static builder() {
         const ret = wasm.classbuilder_builder();
         return ClassBuilder.__wrap(ret);

crates/cli/tests/reference/constructor.d.ts

@@ -1,10 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
-*/
 export class ClassConstructor {
   free(): void;
-/**
-*/
   constructor();
 }

crates/cli/tests/reference/constructor.js

@@ -27,8 +27,7 @@ function getStringFromWasm0(ptr, len) {
 const ClassConstructorFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_classconstructor_free(ptr >>> 0, 1));
-/**
-*/
+
 export class ClassConstructor {
 
     __destroy_into_raw() {
@@ -42,8 +41,6 @@ export class ClassConstructor {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_classconstructor_free(ptr, 0);
     }
-    /**
-    */
     constructor() {
         const ret = wasm.classconstructor_new();
         this.__wbg_ptr = ret >>> 0;

crates/cli/tests/reference/enums.d.ts

@@ -1,27 +1,25 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
-* @param {Color} color
-* @returns {Color}
-*/
+ * @param {Color} color
+ * @returns {Color}
+ */
 export function enum_echo(color: Color): Color;
 /**
-* @param {Color | undefined} [color]
-* @returns {Color | undefined}
-*/
+ * @param {Color | undefined} [color]
+ * @returns {Color | undefined}
+ */
 export function option_enum_echo(color?: Color): Color | undefined;
 /**
-* @param {Color} color
-* @returns {ColorName}
-*/
+ * @param {Color} color
+ * @returns {ColorName}
+ */
 export function get_name(color: Color): ColorName;
 /**
-* @param {ColorName | undefined} [color]
-* @returns {ColorName | undefined}
-*/
+ * @param {ColorName | undefined} [color]
+ * @returns {ColorName | undefined}
+ */
 export function option_string_enum_echo(color?: ColorName): ColorName | undefined;
-/**
-*/
 export enum Color {
   Green = 0,
   Yellow = 1,

crates/cli/tests/reference/enums.js

@@ -24,9 +24,9 @@ function getStringFromWasm0(ptr, len) {
     return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
 }
 /**
-* @param {Color} color
-* @returns {Color}
-*/
+ * @param {Color} color
+ * @returns {Color}
+ */
 export function enum_echo(color) {
     const ret = wasm.enum_echo(color);
     return ret;
@@ -36,34 +36,32 @@ function isLikeNone(x) {
     return x === undefined || x === null;
 }
 /**
-* @param {Color | undefined} [color]
-* @returns {Color | undefined}
-*/
+ * @param {Color | undefined} [color]
+ * @returns {Color | undefined}
+ */
 export function option_enum_echo(color) {
     const ret = wasm.option_enum_echo(isLikeNone(color) ? 3 : color);
     return ret === 3 ? undefined : ret;
 }
 
 /**
-* @param {Color} color
-* @returns {ColorName}
-*/
+ * @param {Color} color
+ * @returns {ColorName}
+ */
 export function get_name(color) {
     const ret = wasm.get_name(color);
     return ["green","yellow","red",][ret];
 }
 
 /**
-* @param {ColorName | undefined} [color]
-* @returns {ColorName | undefined}
-*/
+ * @param {ColorName | undefined} [color]
+ * @returns {ColorName | undefined}
+ */
 export function option_string_enum_echo(color) {
     const ret = wasm.option_string_enum_echo(color == undefined ? 4 : ((["green","yellow","red",].indexOf(color) + 1 || 4) - 1));
     return ["green","yellow","red",][ret];
 }
 
-/**
-*/
 export const Color = Object.freeze({ Green:0,"0":"Green",Yellow:1,"1":"Yellow",Red:2,"2":"Red", });
 
 export function __wbindgen_throw(arg0, arg1) {

crates/cli/tests/reference/import-catch.d.ts

@@ -1,5 +1,3 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
-*/
 export function exported(): void;

crates/cli/tests/reference/import-catch.js

@@ -49,8 +49,7 @@ function takeObject(idx) {
     dropObject(idx);
     return ret;
 }
-/**
-*/
+
 export function exported() {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);

crates/cli/tests/reference/nop.d.ts

@@ -1,5 +1,3 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
-*/
 export function nop(): void;

crates/cli/tests/reference/nop.js

@@ -3,8 +3,7 @@ export function __wbg_set_wasm(val) {
     wasm = val;
 }
 
-/**
-*/
+
 export function nop() {
     wasm.nop();
 }

crates/cli/tests/reference/pointers.d.ts

@@ -1,12 +1,12 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
-* @param {number} input
-* @returns {number}
-*/
+ * @param {number} input
+ * @returns {number}
+ */
 export function const_pointer(input: number): number;
 /**
-* @param {number} input
-* @returns {number}
-*/
+ * @param {number} input
+ * @returns {number}
+ */
 export function mut_pointer(input: number): number;