Support descriptions for JS/TS param/return comments

[codehearts]

Motivation

The generated JS and TS doc comments provide no descriptions for the parameters or return values. Some developers may want this information for additional context in editor tooltips

Proposed Solution

I'm not sure what the ideal solution would be, but I could see a specially formatted line in the Rust comment being treated as the description for an items:

/// param variable_name: The description starts here

Or possible some sort of annotation

#[wasm_bindgen(param = variable_name, description = The description starts here)]

Alternatives

The current alternative is to document the variables in the doc body, but editor tooltips will not show a description for the variables or return value in their tooltips and some developers may not like this

Additional Context

I saw the discussion in #57 when generated comments were initially added, but there was no followup on adding this feature since Rust has no commenting convention for this

My motivation for opening this issue stems from Node.js developers at my company wanting more fully-fleshed out docs available to them when using our bound Node.js modules

[alexcrichton]

Thanks for the report! I think this'd be a pretty reasonable feature to add!

[codehearts]

I'd love to take a crack at this, is there a way to get feedback on which approach to take towards implementing this?

[alexcrichton]

Sure yeah! It's probably good to comment here about a possible concrete design before implementing it, and that way anyone interested can likely help chime in and give feedback.

One question I'd have, we should copy documentation from the Rust source to the JS source, so I think this could be "solved" by writing the Rust documentation in the way that JS expects, right? Is that something you'd prefer to not do though?

[codehearts]

That's a thought, maybe if a JS-doc formatted line exists for a variable it can be copied verbatim into the generated output. Otherwise, it generates the documentation as it currently does

Maybe leaving the type field blank causes bindgen to fill it out for you, I do really like how that ensures your docs match your Rust types

Rust	JS
///	* @param my_var {string}
/// @param my_var {} My string var	* @param my_var {string} My string var
/// @param my_var {string} My string var	* @param my_var {string} My string var

This lines up with what I do currently for documenting throws, I end my Rust comment with /// @throws {TypeError} When a non-string is passed so the generated JS comment looks right

[alexcrichton]

I'm mainly worried that inference of parameter strings and filling out types and such might get pretty hairy with respect to parsing and such. In theory you could just write all the JS docs that you would otherwise write today, and that should get rendered on the other end? We could perhaps fill in docs if all documentation is missing though.

I largely just want to make sure that we don't add too much doc comment parsing to wasm-bindgen because that may not be worth the complexity that it brings.

[codehearts]

Oh, an attribute to disable generated JsDoc comments could work! It'd explicitly show that docs are not generated for an item and would fit in with the current design

I agree on limiting the doc parsing. I think this approach would be sufficient, although I'll sorely miss the autogenerated types. Maybe a special annotation like {js_type:my_var} could be added just to make this convenience available

[codehearts]

Alternatively, I saw your comment on #1691 and thought this could implement that pattern for consistency (depending on how that issue gets implemented):

#[wasm_bindgen(javascript(my_var = "My string var"))]

I'm not sure how practical that would be since you could have lots of variables with relatively long descriptions, meaning your annotations would be huge

[alexcrichton]

Also to be clear I'm not against doing something here, it's more of that I think we'll want to keep it pretty simple as opposed to adding a specific parser just for documentation comments.

[codehearts]

I just noticed parameter attributes were added to Rust 1.39.0 and if anything, that seems like the right way to define extra properties for parameters (or parameter docs, if that's ever fleshed out and made standard). I couldn't figure out if there was a roadmap for non-inert macro support, but I'm happy waiting until that becomes stable to implement this

[alexcrichton]

That's also a possibility yeah! Although it's hard to shake the feeling from my perspective at least of why the Rust documentation would want to be separated so much from the JS documentation, it seems like you'd want the docs to show up in both places?

[codehearts]

Yeah, that would be ideal… I'm assuming if parameter docs become a stabilized feature, those would likely show in the generated Rust docs and could be used to generate the JS

I think in the meantime, having a flag to disable JS doc generation and allowing devs to define them manually in the Rust doc comments is best for now

[rouzwelt]

we would also need something for specifying typescript return type of a method/fn, as discussed in my issue #4377 which is closed in favor of this issue, just mentioning it here so it doesnt get overlooked 😄
also would be nice if we can have a rough estimate timeline of when this might be added.

[daxpedda]

I will not be likely to work on this, but I'm happy to review a detailed proposal and the following PR.

[rouzwelt]

I will not be likely to work on this, but I'm happy to review a detailed proposal and the following PR.

can we spread it into smaller chunks/PRs? so smaller things can land sooner and those that need more work land later on incrementally.
Like let's say, I suppose adding a ts fn return type attr would not be much work and can be a small PR on its own, and then attr for fn args can be its own PR for jsdoc and tsdoc, or maybe some other way.

if thats desirable, Im happy to have a go at it and do it incrementally as having smaller PRs and pieces would make it much easier for me as Im occupied with other stuff too

[daxpedda]

Sure! But unfortunately the proposal itself still has to be comprehensive unless we are talking about an unstable feature.

[rouzwelt]

Sure! But unfortunately the proposal itself still has to be comprehensive unless we are talking about an unstable feature.

I'll submit the proposal with a PR shortly, it was way less work than I assumed, the whole thing can be done with pretty much very minimal additions.
Just as a snippet of my what im coming up with (would appreciate your initial thoughts and suggestions):

also one other thing to ask, Im a bit lost on where to add test coverage for the changes, would appreciate any help/hints/tips. one I was able to locate is crates/macro/ui-tests, possibly other one is crates/typescript-tests and also crates/cli/tests/reference. anywhere else besides these 3 places that test coverage should be added to?

[rouzwelt]

@daxpedda would like to hear your suggestion on where to add test coverage

[rouzwelt]

@daxpedda I just submitted my draft PR, looking forward for your review