Smarter enhancement of JSDoc comments with a JSDoc parser #4310
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Resolves #4223.
Resolves #1847.
This PR improves the type information is added to JSDoc comments. Instead of just adding
@param
and@returns
tags to existing JSDoc comments, WBG will now parse the existing comment and add type information to existing tags (if any). This makesskip_jsdoc
virtually unnecessary, since WBG won't generate tag that conflict with existing tags anymore. (Note thatskip_jsdoc
still has niche use cases.)Example:
This behavior can be turned off with
skip_jsdoc
With the new smarter behavior, users documenting their code with standard JSDoc/TSDoc can now use
@param
/@returns
tags without having WBG mess it up or having to usingskip_jsdoc
and duplicating the type info. WBG's JSDoc comment enhancement now works together with our users.Moving forward, I believe that we should teach people to WBG will automatically add type information for them, and they should not manually add type info to
@param
and@returns
tags at all. This has several advantages, one being that users don't get any ideas about trying to declare custom types as@param {1 | 2 | 3} arg
, which does not affect the TS types. Once we have a way for users to declare custom TS type annotations, they will just work with the new JSDoc enhancements.The main complexity of this PR is:
The parser is written in a way that makes any string valid JSDoc. This can also be seen by the signature of the parsing function:
fn parse(comment: &str) -> JsDoc
. The doc comment on the function explains how this is done. In generally, I extensively documented the parser. If you have any question regarding how the parser works, the answer is probably in a comment.For the tags that are supported, the implementation is fairly complete. The parser supports all sorts of mean constructs like multiple-line TS types, comments in TS types, default values, and argument paths (e.g.
@param {number} arg0.age
). So it's fairly complete for what it supports. See the snapshot test for many more examples.