-
Notifications
You must be signed in to change notification settings - Fork 131
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Flexible parsing of param/typeParam #206
Conversation
3513e61
to
224af31
Compare
@rbuckton Sorry for the slow response. Looking at it now... |
The optional name rule seems to be losing tokens. Consider this input: /**
* Example 1
*
* @param [n - this is
* the description
*
* @public
*/ It correctly reports The TSDoc parser generally aims for every input character to be associated with some AST node somewhere in the parse tree, even if the input character caused an error to be reported. |
Also this input produces two errors for the same character, based on different interpretations of /**
* Example 2
*
* @param { test
*/
(4,11): The @param block should not include a JSDoc-style '{type}'
(4,11): Expecting a TSDoc tag starting with "{@" Generally the parser tries to avoid this by consuming the token after reporting an error. If there isn't a natural AST node to associate it with, we can create a |
I will see if I can fix these issues... |
I've almost finished fixes for them. |
The problem with the second case is that we parse |
The issue seems to be that the JSDoc junk is not being registered as excerpts of
The JSDoc expressions introduce new characters that need to be represented somehow. Your PR starts us down the road of "lax" parsing for legacy notations. It's slightly awkard because junk characters can appear anywhere, whereas the current AST expects tokens to fit into a well-formed structure. Also note that excerpts determine syntax highlighting, so we do need to add these junk tokens to the AST tree somehow. I'm proposing we introduce a term "cruft" for naming excerpts that are ignored junk. We can give them all the same color (e.g. gray), ignoring any legacy meanings. So we'll add two new "cruft" excerpts to
This feels not ideal. The right solution is the AST redesign that we discussed before. But until then, we should probably try to work within the existing parser design. |
I just pushed an update that should pretty much do that. |
d0bdb6f
to
97ddf6c
Compare
97ddf6c
to
57ffe4d
Compare
@rbuckton Thanks very much for implementing this feature! It's really useful! |
Improves parsing for
@param
and@typeParam
blocks to handle the following cases:For each of the above cases, a warning is issued (and can be ignored via configuration). In the case of the missing hyphen, this fixes the case where the parameter name was not included in the parameter description.
When parsing out a JSDoc-style type or value (in the case of a parameter default), the parser handles balanced brackets/braces, quoted strings, and escaped quote-marks.
Fixes: #128