diff --git a/CHANGELOG.md b/CHANGELOG.md index 5792f38fbc7..f1dde9c0803 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/crates/cli-support/src/js/mod.rs b/crates/cli-support/src/js/mod.rs index b053bbd526c..b7523e6089e 100644 --- a/crates/cli-support/src/js/mod.rs +++ b/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 { 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); diff --git a/crates/cli-support/src/lib.rs b/crates/cli-support/src/lib.rs index 8c49ddbc1a6..bd47dfc43b0 100755 --- a/crates/cli-support/src/lib.rs +++ b/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; } } diff --git a/crates/cli/tests/reference/add.d.ts b/crates/cli/tests/reference/add.d.ts index a8ee5f2e475..73827342908 100644 --- a/crates/cli/tests/reference/add.d.ts +++ b/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; diff --git a/crates/cli/tests/reference/add.js b/crates/cli/tests/reference/add.js index 4828d396ae5..51914d7d296 100644 --- a/crates/cli/tests/reference/add.js +++ b/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; diff --git a/crates/cli/tests/reference/anyref-import-catch.d.ts b/crates/cli/tests/reference/anyref-import-catch.d.ts index 3e2ffc07207..091dbcc51a6 100644 --- a/crates/cli/tests/reference/anyref-import-catch.d.ts +++ b/crates/cli/tests/reference/anyref-import-catch.d.ts @@ -1,5 +1,3 @@ /* tslint:disable */ /* eslint-disable */ -/** -*/ export function exported(): void; diff --git a/crates/cli/tests/reference/anyref-import-catch.js b/crates/cli/tests/reference/anyref-import-catch.js index 9fb5c31b135..d89f629f896 100644 --- a/crates/cli/tests/reference/anyref-import-catch.js +++ b/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); diff --git a/crates/cli/tests/reference/anyref-nop.d.ts b/crates/cli/tests/reference/anyref-nop.d.ts index b9f9648536e..b7f28e8f7af 100644 --- a/crates/cli/tests/reference/anyref-nop.d.ts +++ b/crates/cli/tests/reference/anyref-nop.d.ts @@ -1,5 +1,3 @@ /* tslint:disable */ /* eslint-disable */ -/** -*/ export function foo(): void; diff --git a/crates/cli/tests/reference/anyref-nop.js b/crates/cli/tests/reference/anyref-nop.js index 236d93eaf93..48574501fbc 100644 --- a/crates/cli/tests/reference/anyref-nop.js +++ b/crates/cli/tests/reference/anyref-nop.js @@ -3,8 +3,7 @@ export function __wbg_set_wasm(val) { wasm = val; } -/** -*/ + export function foo() { wasm.foo(); } diff --git a/crates/cli/tests/reference/async-number.d.ts b/crates/cli/tests/reference/async-number.d.ts index d7204543623..bc2b7e88a3c 100644 --- a/crates/cli/tests/reference/async-number.d.ts +++ b/crates/cli/tests/reference/async-number.d.ts @@ -1,6 +1,6 @@ /* tslint:disable */ /* eslint-disable */ /** -* @returns {Promise} -*/ + * @returns {Promise} + */ export function foo(): Promise; diff --git a/crates/cli/tests/reference/async-void.d.ts b/crates/cli/tests/reference/async-void.d.ts index 83335802b7e..b5b19290f13 100644 --- a/crates/cli/tests/reference/async-void.d.ts +++ b/crates/cli/tests/reference/async-void.d.ts @@ -1,6 +1,6 @@ /* tslint:disable */ /* eslint-disable */ /** -* @returns {Promise} -*/ + * @returns {Promise} + */ export function foo(): Promise; diff --git a/crates/cli/tests/reference/builder.d.ts b/crates/cli/tests/reference/builder.d.ts index ede348c9632..3a92bacdb43 100644 --- a/crates/cli/tests/reference/builder.d.ts +++ b/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; } diff --git a/crates/cli/tests/reference/builder.js b/crates/cli/tests/reference/builder.js index b491793222a..1781b4dbe06 100644 --- a/crates/cli/tests/reference/builder.js +++ b/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); diff --git a/crates/cli/tests/reference/constructor.d.ts b/crates/cli/tests/reference/constructor.d.ts index f35e8c72fa1..f2ac36f4b25 100644 --- a/crates/cli/tests/reference/constructor.d.ts +++ b/crates/cli/tests/reference/constructor.d.ts @@ -1,10 +1,6 @@ /* tslint:disable */ /* eslint-disable */ -/** -*/ export class ClassConstructor { free(): void; -/** -*/ constructor(); } diff --git a/crates/cli/tests/reference/constructor.js b/crates/cli/tests/reference/constructor.js index ffac02b997a..e55a1e9e9bf 100644 --- a/crates/cli/tests/reference/constructor.js +++ b/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; diff --git a/crates/cli/tests/reference/enums.d.ts b/crates/cli/tests/reference/enums.d.ts index 1ffd4249837..556f8085651 100644 --- a/crates/cli/tests/reference/enums.d.ts +++ b/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, diff --git a/crates/cli/tests/reference/enums.js b/crates/cli/tests/reference/enums.js index 07d1cf32427..bbfdc2c5859 100644 --- a/crates/cli/tests/reference/enums.js +++ b/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) { diff --git a/crates/cli/tests/reference/import-catch.d.ts b/crates/cli/tests/reference/import-catch.d.ts index 3e2ffc07207..091dbcc51a6 100644 --- a/crates/cli/tests/reference/import-catch.d.ts +++ b/crates/cli/tests/reference/import-catch.d.ts @@ -1,5 +1,3 @@ /* tslint:disable */ /* eslint-disable */ -/** -*/ export function exported(): void; diff --git a/crates/cli/tests/reference/import-catch.js b/crates/cli/tests/reference/import-catch.js index ad340f07bbd..4c4d0284851 100644 --- a/crates/cli/tests/reference/import-catch.js +++ b/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); diff --git a/crates/cli/tests/reference/nop.d.ts b/crates/cli/tests/reference/nop.d.ts index c285bc0f2f6..be1200f247d 100644 --- a/crates/cli/tests/reference/nop.d.ts +++ b/crates/cli/tests/reference/nop.d.ts @@ -1,5 +1,3 @@ /* tslint:disable */ /* eslint-disable */ -/** -*/ export function nop(): void; diff --git a/crates/cli/tests/reference/nop.js b/crates/cli/tests/reference/nop.js index 86488ff66d1..7369fb615be 100644 --- a/crates/cli/tests/reference/nop.js +++ b/crates/cli/tests/reference/nop.js @@ -3,8 +3,7 @@ export function __wbg_set_wasm(val) { wasm = val; } -/** -*/ + export function nop() { wasm.nop(); } diff --git a/crates/cli/tests/reference/pointers.d.ts b/crates/cli/tests/reference/pointers.d.ts index 2ce096435b5..145577b8753 100644 --- a/crates/cli/tests/reference/pointers.d.ts +++ b/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; diff --git a/crates/cli/tests/reference/pointers.js b/crates/cli/tests/reference/pointers.js index cf088c2e711..45fb0349a22 100644 --- a/crates/cli/tests/reference/pointers.js +++ b/crates/cli/tests/reference/pointers.js @@ -4,18 +4,18 @@ export function __wbg_set_wasm(val) { } /** -* @param {number} input -* @returns {number} -*/ + * @param {number} input + * @returns {number} + */ export function const_pointer(input) { const ret = wasm.const_pointer(input); return ret >>> 0; } /** -* @param {number} input -* @returns {number} -*/ + * @param {number} input + * @returns {number} + */ export function mut_pointer(input) { const ret = wasm.mut_pointer(input); return ret >>> 0; diff --git a/crates/cli/tests/reference/raw.d.ts b/crates/cli/tests/reference/raw.d.ts index 944af97ab04..fb474c2fabd 100644 --- a/crates/cli/tests/reference/raw.d.ts +++ b/crates/cli/tests/reference/raw.d.ts @@ -1,21 +1,19 @@ /* tslint:disable */ /* eslint-disable */ /** -* @param {number} test -* @returns {number} -*/ + * @param {number} test + * @returns {number} + */ export function test1(test: number): number; -/** -*/ export class Test { free(): void; -/** -* @param {number} test -* @returns {Test} -*/ + /** + * @param {number} test + * @returns {Test} + */ static test1(test: number): Test; -/** -* @param {number} test -*/ + /** + * @param {number} test + */ test2(test: number): void; } diff --git a/crates/cli/tests/reference/raw.js b/crates/cli/tests/reference/raw.js index 6b831debb89..65e2bdccd73 100644 --- a/crates/cli/tests/reference/raw.js +++ b/crates/cli/tests/reference/raw.js @@ -6,26 +6,6 @@ export function __wbg_set_wasm(val) { } -const heap = new Array(128).fill(undefined); - -heap.push(undefined, null, true, false); - -function getObject(idx) { return heap[idx]; } - -let heap_next = heap.length; - -function dropObject(idx) { - if (idx < 132) return; - heap[idx] = heap_next; - heap_next = idx; -} - -function takeObject(idx) { - const ret = getObject(idx); - dropObject(idx); - return ret; -} - const lTextDecoder = typeof TextDecoder === 'undefined' ? (0, module.require)('util').TextDecoder : TextDecoder; let cachedTextDecoder = new lTextDecoder('utf-8', { ignoreBOM: true, fatal: true }); @@ -45,10 +25,30 @@ function getStringFromWasm0(ptr, len) { ptr = ptr >>> 0; return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len)); } + +const heap = new Array(128).fill(undefined); + +heap.push(undefined, null, true, false); + +function getObject(idx) { return heap[idx]; } + +let heap_next = heap.length; + +function dropObject(idx) { + if (idx < 132) return; + heap[idx] = heap_next; + heap_next = idx; +} + +function takeObject(idx) { + const ret = getObject(idx); + dropObject(idx); + return ret; +} /** -* @param {number} test -* @returns {number} -*/ + * @param {number} test + * @returns {number} + */ export function test1(test) { const ret = wasm.test1(test); return ret >>> 0; @@ -66,8 +66,7 @@ function addHeapObject(obj) { const TestFinalization = (typeof FinalizationRegistry === 'undefined') ? { register: () => {}, unregister: () => {} } : new FinalizationRegistry(ptr => wasm.__wbg_test_free(ptr >>> 0, 1)); -/** -*/ + export class Test { static __wrap(ptr) { @@ -90,26 +89,21 @@ export class Test { wasm.__wbg_test_free(ptr, 0); } /** - * @param {number} test - * @returns {Test} - */ + * @param {number} test + * @returns {Test} + */ static test1(test) { const ret = wasm.test_test1(test); return Test.__wrap(ret); } /** - * @param {number} test - */ + * @param {number} test + */ test2(test) { wasm.test_test2(this.__wbg_ptr, test); } } -export function __wbg_test2_39fe629b9aa739cf() { - const ret = test2(); - return addHeapObject(ret); -}; - export function __wbindgen_object_drop_ref(arg0) { takeObject(arg0); }; @@ -118,3 +112,8 @@ export function __wbindgen_throw(arg0, arg1) { throw new Error(getStringFromWasm0(arg0, arg1)); }; +export function __wbg_test2_39fe629b9aa739cf() { + const ret = test2(); + return addHeapObject(ret); +}; + diff --git a/crates/cli/tests/reference/result-string.d.ts b/crates/cli/tests/reference/result-string.d.ts index 50967eed5cf..2e707cffa43 100644 --- a/crates/cli/tests/reference/result-string.d.ts +++ b/crates/cli/tests/reference/result-string.d.ts @@ -1,6 +1,6 @@ /* tslint:disable */ /* eslint-disable */ /** -* @returns {string} -*/ + * @returns {string} + */ export function exported(): string; diff --git a/crates/cli/tests/reference/result-string.js b/crates/cli/tests/reference/result-string.js index 6d3c47f400b..caa17738225 100644 --- a/crates/cli/tests/reference/result-string.js +++ b/crates/cli/tests/reference/result-string.js @@ -62,8 +62,8 @@ function getStringFromWasm0(ptr, len) { return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len)); } /** -* @returns {string} -*/ + * @returns {string} + */ export function exported() { let deferred2_0; let deferred2_1; diff --git a/crates/cli/tests/reference/skip-jsdoc.d.ts b/crates/cli/tests/reference/skip-jsdoc.d.ts index dda14e231eb..f295e357377 100644 --- a/crates/cli/tests/reference/skip-jsdoc.d.ts +++ b/crates/cli/tests/reference/skip-jsdoc.d.ts @@ -1,9 +1,9 @@ /* tslint:disable */ /* eslint-disable */ /** -* Manually documented function -* -* @param {number} arg - This is my arg. It is mine. -* @returns to whence I came -*/ + * Manually documented function + * + * @param {number} arg - This is my arg. It is mine. + * @returns to whence I came + */ export function docme(arg: number): number; diff --git a/crates/cli/tests/reference/skip-jsdoc.js b/crates/cli/tests/reference/skip-jsdoc.js index a617a8f3098..66a9f7870d1 100644 --- a/crates/cli/tests/reference/skip-jsdoc.js +++ b/crates/cli/tests/reference/skip-jsdoc.js @@ -4,11 +4,11 @@ export function __wbg_set_wasm(val) { } /** -* Manually documented function -* -* @param {number} arg - This is my arg. It is mine. -* @returns to whence I came -*/ + * Manually documented function + * + * @param {number} arg - This is my arg. It is mine. + * @returns to whence I came + */ export function docme(arg) { const ret = wasm.docme(arg); return ret >>> 0; diff --git a/crates/cli/tests/reference/string-arg.d.ts b/crates/cli/tests/reference/string-arg.d.ts index 701afc6b2d4..d103e1337e1 100644 --- a/crates/cli/tests/reference/string-arg.d.ts +++ b/crates/cli/tests/reference/string-arg.d.ts @@ -1,6 +1,6 @@ /* tslint:disable */ /* eslint-disable */ /** -* @param {string} a -*/ + * @param {string} a + */ export function foo(a: string): void; diff --git a/crates/cli/tests/reference/string-arg.js b/crates/cli/tests/reference/string-arg.js index 62d6ce47201..cc037461669 100644 --- a/crates/cli/tests/reference/string-arg.js +++ b/crates/cli/tests/reference/string-arg.js @@ -82,8 +82,8 @@ function passStringToWasm0(arg, malloc, realloc) { return ptr; } /** -* @param {string} a -*/ + * @param {string} a + */ export function foo(a) { const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc); const len0 = WASM_VECTOR_LEN;