Skip to content

Commit 1203f18

Browse files
liuxingbaoyuliuxingbaoyu
authored
chore: Clean up parser comments (#15252)
1 parent bdfd643 commit 1203f18

9 files changed

Lines changed: 65 additions & 144 deletions

File tree

‎packages/babel-parser/src/parser/comments.ts‎

Lines changed: 28 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,38 @@ import type { Undone } from "./node";
77

88
/**
99
* A whitespace token containing comments
10-
* @typedef CommentWhitespace
11-
* @type {object}
12-
* @property {number} start - the start of the whitespace token.
13-
* @property {number} end - the end of the whitespace token.
14-
* @property {Array<Comment>} comments - the containing comments
15-
* @property {Node | null} leadingNode - the immediately preceding AST node of the whitespace token
16-
* @property {Node | null} trailingNode - the immediately following AST node of the whitespace token
17-
* @property {Node | null} containingNode - the innermost AST node containing the whitespace
18-
* with minimal size (|end - start|)
1910
*/
2011
export type CommentWhitespace = {
12+
/**
13+
* the start of the whitespace token.
14+
*/
2115
start: number;
16+
/**
17+
* the end of the whitespace token.
18+
*/
2219
end: number;
20+
/**
21+
* the containing comments
22+
*/
2323
comments: Array<Comment>;
24+
/**
25+
* the immediately preceding AST node of the whitespace token
26+
*/
2427
leadingNode: Node | null;
28+
/**
29+
* the immediately following AST node of the whitespace token
30+
*/
2531
trailingNode: Node | null;
32+
/**
33+
* the innermost AST node containing the whitespace with minimal size (|end - start|)
34+
*/
2635
containingNode: Node | null;
2736
};
2837

2938
/**
3039
* Merge comments with node's trailingComments or assign comments to be
3140
* trailingComments. New comments will be placed before old comments
3241
* because the commentStack is enumerated reversely.
33-
*
34-
* @param {Undone<Node>} node
35-
* @param {Array<Comment>} comments
3642
*/
3743
function setTrailingComments(node: Undone<Node>, comments: Array<Comment>) {
3844
if (node.trailingComments === undefined) {
@@ -46,9 +52,6 @@ function setTrailingComments(node: Undone<Node>, comments: Array<Comment>) {
4652
* Merge comments with node's leadingComments or assign comments to be
4753
* leadingComments. New comments will be placed before old comments
4854
* because the commentStack is enumerated reversely.
49-
*
50-
* @param {Undone<Node>} node
51-
* @param {Array<Comment>} comments
5255
*/
5356
function setLeadingComments(node: Undone<Node>, comments: Array<Comment>) {
5457
if (node.leadingComments === undefined) {
@@ -62,9 +65,6 @@ function setLeadingComments(node: Undone<Node>, comments: Array<Comment>) {
6265
* Merge comments with node's innerComments or assign comments to be
6366
* innerComments. New comments will be placed before old comments
6467
* because the commentStack is enumerated reversely.
65-
*
66-
* @param {Undone<Node>} node
67-
* @param {Array<Comment>} comments
6868
*/
6969
export function setInnerComments(
7070
node: Undone<Node>,
@@ -81,10 +81,6 @@ export function setInnerComments(
8181
* Given node and elements array, if elements has non-null element,
8282
* merge comments to its trailingComments, otherwise merge comments
8383
* to node's innerComments
84-
*
85-
* @param {Undone<Node>} node
86-
* @param {Array<Node>} elements
87-
* @param {Array<Comment>} comments
8884
*/
8985
function adjustInnerComments(
9086
node: Undone<Node>,
@@ -103,7 +99,6 @@ function adjustInnerComments(
10399
}
104100
}
105101

106-
/** @class CommentsParser */
107102
export default class CommentsParser extends BaseParser {
108103
addComment(comment: Comment): void {
109104
if (this.filename) comment.loc.filename = this.filename;
@@ -113,10 +108,6 @@ export default class CommentsParser extends BaseParser {
113108
/**
114109
* Given a newly created AST node _n_, attach _n_ to a comment whitespace _w_ if applicable
115110
* {@see {@link CommentWhitespace}}
116-
*
117-
* @param {Node} node
118-
* @returns {void}
119-
* @memberof CommentsParser
120111
*/
121112
processComment(node: Node): void {
122113
const { commentStack } = this.state;
@@ -158,8 +149,6 @@ export default class CommentsParser extends BaseParser {
158149
/**
159150
* Assign the comments of comment whitespaces to related AST nodes.
160151
* Also adjust innerComments following trailing comma.
161-
*
162-
* @memberof CommentsParser
163152
*/
164153
finalizeComment(commentWS: CommentWhitespace) {
165154
const { comments } = commentWS;
@@ -219,8 +208,6 @@ export default class CommentsParser extends BaseParser {
219208
* to each comment whitespace. Used only in parseExpression
220209
* where the top level AST node is _not_ Program
221210
* {@see {@link CommentsParser#finalizeComment}}
222-
*
223-
* @memberof CommentsParser
224211
*/
225212
finalizeRemainingComments() {
226213
const { commentStack } = this.state;
@@ -230,24 +217,25 @@ export default class CommentsParser extends BaseParser {
230217
this.state.commentStack = [];
231218
}
232219

220+
/* eslint-disable no-irregular-whitespace */
233221
/**
234222
* Reset previous node trailing comments. Used in object / class
235223
* property parsing. We parse `async`, `static`, `set` and `get`
236224
* as an identifier but may reinterpret it into an async/static/accessor
237225
* method later. In this case the identifier is not part of the AST and we
238226
* should sync the knowledge to commentStacks
239227
*
240-
* For example, when parsing */
241-
// async /* 1 */ function f() {}
242-
/*
243-
* the comment whitespace "* 1 *" has leading node Identifier(async). When
244-
* we see the function token, we create a Function node and mark "* 1 *" as
245-
* inner comments. So "* 1 *" should be detached from the Identifier node.
228+
* For example, when parsing
229+
* ```
230+
* async /* 1 *​/ function f() {}
231+
* ```
232+
* the comment whitespace `/* 1 *​/` has leading node Identifier(async). When
233+
* we see the function token, we create a Function node and mark `/* 1 *​/` as
234+
* inner comments. So `/* 1 *​/` should be detached from the Identifier node.
246235
*
247-
* @param {N.Node} node the last finished AST node _before_ current token
248-
* @returns
249-
* @memberof CommentsParser
236+
* @param node the last finished AST node _before_ current token
250237
*/
238+
/* eslint-enable no-irregular-whitespace */
251239
resetPreviousNodeTrailingComments(node: Node) {
252240
const { commentStack } = this.state;
253241
const { length } = commentStack;
@@ -264,10 +252,6 @@ export default class CommentsParser extends BaseParser {
264252
*
265253
* This is used to properly attach comments around parenthesized
266254
* expressions as leading/trailing comments of the inner expression.
267-
*
268-
* @param {Node} node
269-
* @param {number} start
270-
* @param {number} end
271255
*/
272256
takeSurroundingComments(node: Node, start: number, end: number) {
273257
const { commentStack } = this.state;

‎packages/babel-parser/src/parser/lval.ts‎

Lines changed: 25 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -84,19 +84,18 @@ export default abstract class LValParser extends NodeUtils {
8484
/**
8585
* Convert existing expression atom to assignable pattern
8686
* if possible. Also checks invalid destructuring targets:
87-
88-
- Parenthesized Destructuring patterns
89-
- RestElement is not the last element
90-
- Missing `=` in assignment pattern
91-
92-
NOTE: There is a corresponding "isAssignable" method.
93-
When this one is updated, please check if also that one needs to be updated.
94-
95-
* @param {Node} node The expression atom
96-
* @param {boolean} [isLHS=false] Whether we are parsing a LeftHandSideExpression.
97-
* If isLHS is `true`, the following cases are allowed: `[(a)] = [0]`, `[(a.b)] = [0]`
98-
* If isLHS is `false`, we are in an arrow function parameters list.
99-
* @memberof LValParser
87+
*
88+
* - Parenthesized Destructuring patterns
89+
* - RestElement is not the last element
90+
* - Missing `=` in assignment pattern
91+
*
92+
* NOTE: There is a corresponding "isAssignable" method.
93+
* When this one is updated, please check if also that one needs to be updated.
94+
*
95+
* @param node The expression atom
96+
* @param isLHS Whether we are parsing a LeftHandSideExpression.
97+
* If isLHS is `true`, the following cases are allowed: `[(a)] = [0]`, `[(a.b)] = [0]`
98+
* If isLHS is `false`, we are in an arrow function parameters list.
10099
*/
101100
toAssignable(node: Node, isLHS: boolean = false): void {
102101
let parenthesized = undefined;
@@ -108,7 +107,7 @@ export default abstract class LValParser extends NodeUtils {
108107
// i.e. `([(a) = []] = []) => {}`
109108
// see also `recordArrowParemeterBindingError` signature in packages/babel-parser/src/util/expression-scope.js
110109
if (parenthesized.type === "Identifier") {
111-
this.expressionScope.recordArrowParemeterBindingError(
110+
this.expressionScope.recordArrowParameterBindingError(
112111
Errors.InvalidParenthesizedAssignment,
113112
{ at: node },
114113
);
@@ -510,15 +509,14 @@ export default abstract class LValParser extends NodeUtils {
510509
* The `string`-only return option is actually just a shorthand for:
511510
* `[key: string, parenthesized: false]`.
512511
*
513-
* @param {NodeType} type A Node `type` string
514-
* @param {boolean} isUnparenthesizedInAssign
512+
* @param type A Node `type` string
513+
* @param isUnparenthesizedInAssign
515514
* Whether the node in question is unparenthesized and its parent
516515
* is either an assignment pattern or an assignment expression.
517-
* @param {BindingTypes} binding
516+
* @param binding
518517
* The binding operation that is being considered for this potential
519518
* LVal.
520-
* @returns { boolean | string | [string, boolean] }
521-
* `true` or `false` if we can immediately determine whether the node
519+
* @returns `true` or `false` if we can immediately determine whether the node
522520
* type in question can be treated as an `LVal`.
523521
* A `string` key to traverse if we must check this child.
524522
* A `[string, boolean]` tuple if we need to check this child and
@@ -548,31 +546,30 @@ export default abstract class LValParser extends NodeUtils {
548546
/**
549547
* Verify that a target expression is an lval (something that can be assigned to).
550548
*
551-
* @param {Expression} expression The expression in question to check.
552-
* @param {Object} options A set of options described below.
553-
* @param {LValAncestor} options.in
549+
* @param expression The expression in question to check.
550+
* @param options A set of options described below.
551+
* @param options.in
554552
* The relevant ancestor to provide context information for the error
555553
* if the check fails.
556-
* @param {BindingTypes} [options.binding=BIND_NONE]
554+
* @param options.binding
557555
* The desired binding type. If the given expression is an identifier
558556
* and `binding` is not `BIND_NONE`, `checkLVal` will register binding
559557
* to the parser scope See also `src/util/scopeflags.js`
560-
* @param {Set<string>|false} [options.checkClashes=false]
558+
* @param options.checkClashes
561559
* An optional string set to check if an identifier name is included.
562560
* `checkLVal` will add checked identifier name to `checkClashes` It is
563561
* used in tracking duplicates in function parameter lists. If it is
564562
* false, `checkLVal` will skip duplicate checks
565-
* @param {boolean} [options.allowingSloppyLetBinding]
563+
* @param options.allowingSloppyLetBinding
566564
* Whether an identifier named "let" should be allowed in sloppy mode.
567565
* Defaults to `true` unless lexical scope its being used. This property
568566
* is only relevant if the parser's state is in sloppy mode.
569-
* @param {boolean} [options.strictModeChanged=false]
567+
* @param options.strictModeChanged
570568
* Whether an identifier has been parsed in a sloppy context but should
571569
* be reinterpreted as strict-mode. e.g. `(arguments) => { "use strict "}`
572-
* @param {boolean} [options.hasParenthesizedAncestor=false]
570+
* @param options.hasParenthesizedAncestor
573571
* This is only used internally during recursive calls, and you should
574572
* not have to set it yourself.
575-
* @memberof LValParser
576573
*/
577574

578575
checkLVal(

‎packages/babel-parser/src/parser/statement.ts‎

Lines changed: 1 addition & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,6 @@ const keywordRelationalOperator = /in(?:stanceof)?/y;
7373
* tt.templateNonTail => tt.backquote/tt.braceR + tt.template + tt.dollarBraceL
7474
* For performance reasons this routine mutates `tokens`, it is okay
7575
* here since we execute `parseTopLevel` once for every file.
76-
* @param {*} tokens
77-
* @returns
7876
*/
7977
function babel7CompatTokens(tokens: (Token | N.Comment)[], input: string) {
8078
for (let i = 0; i < tokens.length; i++) {
@@ -248,14 +246,8 @@ export default abstract class StatementParser extends ExpressionParser {
248246
return finishedProgram;
249247
}
250248

251-
// TODO
252-
253249
/**
254250
* cast a Statement to a Directive. This method mutates input statement.
255-
*
256-
* @param {N.Statement} stmt
257-
* @returns {N.Directive}
258-
* @memberof StatementParser
259251
*/
260252
stmtToDirective(stmt: N.Statement): N.Directive {
261253
const directive = stmt as any;
@@ -323,9 +315,6 @@ export default abstract class StatementParser extends ExpressionParser {
323315
/**
324316
* Assuming we have seen a contextual `let` and declaration is allowed, check if it
325317
* starts a variable declaration so that it should be interpreted as a keyword.
326-
*
327-
* @returns {boolean}
328-
* @memberof StatementParser
329318
*/
330319
hasFollowingBindingAtom(): boolean {
331320
const next = this.nextTokenStart();
@@ -339,9 +328,6 @@ export default abstract class StatementParser extends ExpressionParser {
339328
/**
340329
* Assuming we have seen a contextual `using` and declaration is allowed, check if it
341330
* starts a variable declaration so that it should be interpreted as a keyword.
342-
*
343-
* @returns {boolean}
344-
* @memberof StatementParser
345331
*/
346332
hasFollowingBindingIdentifier(): boolean {
347333
const next = this.nextTokenStart();
@@ -2982,9 +2968,7 @@ export default abstract class StatementParser extends ExpressionParser {
29822968
/**
29832969
* parse assert entries
29842970
*
2985-
* @see {@link https://tc39.es/proposal-import-assertions/#prod-AssertEntries |AssertEntries}
2986-
* @returns {N.ImportAttribute[]}
2987-
* @memberof StatementParser
2971+
* @see {@link https://tc39.es/proposal-import-assertions/#prod-AssertEntries AssertEntries}
29882972
*/
29892973
parseAssertEntries(): N.ImportAttribute[] {
29902974
const attrs = [];
@@ -3031,8 +3015,6 @@ export default abstract class StatementParser extends ExpressionParser {
30313015
/**
30323016
* parse module attributes
30333017
* @deprecated It will be removed in Babel 8
3034-
* @returns
3035-
* @memberof StatementParser
30363018
*/
30373019
maybeParseModuleAttributes() {
30383020
if (this.match(tt._with) && !this.hasPrecedingLineBreak()) {

‎packages/babel-parser/src/parser/util.ts‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,6 @@ export default abstract class UtilParser extends Tokenizer {
3939
// Forward-declaration: defined in parser/index.js
4040
abstract getScopeHandler(): { new (...args: any): ScopeHandler };
4141

42-
// TODO
43-
4442
addExtra(
4543
node: Partial<Node>,
4644
key: string,
@@ -128,8 +126,6 @@ export default abstract class UtilParser extends Tokenizer {
128126
return skipWhiteSpaceToLineBreak.test(this.input);
129127
}
130128

131-
// TODO
132-
133129
isLineTerminator(): boolean {
134130
return this.eat(tt.semi) || this.canInsertSemicolon();
135131
}
@@ -264,15 +260,15 @@ export default abstract class UtilParser extends Tokenizer {
264260
return tokenIsLiteralPropertyName(this.state.type);
265261
}
266262

267-
/*
263+
/**
268264
* Test if given node is a PrivateName
269265
* will be overridden in ESTree plugin
270266
*/
271267
isPrivateName(node: Node): boolean {
272268
return node.type === "PrivateName";
273269
}
274270

275-
/*
271+
/**
276272
* Return the string value of a given private name
277273
* WITHOUT `#`
278274
* @see {@link https://tc39.es/ecma262/#sec-static-semantics-stringvalue}
@@ -281,7 +277,7 @@ export default abstract class UtilParser extends Tokenizer {
281277
return node.id.name;
282278
}
283279

284-
/*
280+
/**
285281
* Return whether the given node is a member/optional chain that
286282
* contains a private name as its property
287283
* It is overridden in ESTree plugin
@@ -380,7 +376,7 @@ export default abstract class UtilParser extends Tokenizer {
380376
* - **shorthandAssignLoc**: track initializer `=` position
381377
* - **doubleProtoLoc**: track the duplicate `__proto__` key position
382378
* - **privateKey**: track private key `#p` position
383-
* - **optionalParametersLoc**: track the optional paramter (`?`).
379+
* - **optionalParametersLoc**: track the optional parameter (`?`).
384380
* It's only used by typescript and flow plugins
385381
*/
386382
export class ExpressionErrors {

0 commit comments

Comments
 (0)