diff --git a/packages/babel-parser/src/parser/comments.ts b/packages/babel-parser/src/parser/comments.ts index 04e7261c8961..03e2db053db1 100644 --- a/packages/babel-parser/src/parser/comments.ts +++ b/packages/babel-parser/src/parser/comments.ts @@ -7,22 +7,31 @@ import type { Undone } from "./node"; /** * A whitespace token containing comments - * @typedef CommentWhitespace - * @type {object} - * @property {number} start - the start of the whitespace token. - * @property {number} end - the end of the whitespace token. - * @property {Array} comments - the containing comments - * @property {Node | null} leadingNode - the immediately preceding AST node of the whitespace token - * @property {Node | null} trailingNode - the immediately following AST node of the whitespace token - * @property {Node | null} containingNode - the innermost AST node containing the whitespace - * with minimal size (|end - start|) */ export type CommentWhitespace = { + /** + * the start of the whitespace token. + */ start: number; + /** + * the end of the whitespace token. + */ end: number; + /** + * the containing comments + */ comments: Array; + /** + * the immediately preceding AST node of the whitespace token + */ leadingNode: Node | null; + /** + * the immediately following AST node of the whitespace token + */ trailingNode: Node | null; + /** + * the innermost AST node containing the whitespace with minimal size (|end - start|) + */ containingNode: Node | null; }; @@ -30,9 +39,6 @@ export type CommentWhitespace = { * Merge comments with node's trailingComments or assign comments to be * trailingComments. New comments will be placed before old comments * because the commentStack is enumerated reversely. - * - * @param {Undone} node - * @param {Array} comments */ function setTrailingComments(node: Undone, comments: Array) { if (node.trailingComments === undefined) { @@ -46,9 +52,6 @@ function setTrailingComments(node: Undone, comments: Array) { * Merge comments with node's leadingComments or assign comments to be * leadingComments. New comments will be placed before old comments * because the commentStack is enumerated reversely. - * - * @param {Undone} node - * @param {Array} comments */ function setLeadingComments(node: Undone, comments: Array) { if (node.leadingComments === undefined) { @@ -62,9 +65,6 @@ function setLeadingComments(node: Undone, comments: Array) { * Merge comments with node's innerComments or assign comments to be * innerComments. New comments will be placed before old comments * because the commentStack is enumerated reversely. - * - * @param {Undone} node - * @param {Array} comments */ export function setInnerComments( node: Undone, @@ -81,10 +81,6 @@ export function setInnerComments( * Given node and elements array, if elements has non-null element, * merge comments to its trailingComments, otherwise merge comments * to node's innerComments - * - * @param {Undone} node - * @param {Array} elements - * @param {Array} comments */ function adjustInnerComments( node: Undone, @@ -103,7 +99,6 @@ function adjustInnerComments( } } -/** @class CommentsParser */ export default class CommentsParser extends BaseParser { addComment(comment: Comment): void { if (this.filename) comment.loc.filename = this.filename; @@ -113,10 +108,6 @@ export default class CommentsParser extends BaseParser { /** * Given a newly created AST node _n_, attach _n_ to a comment whitespace _w_ if applicable * {@see {@link CommentWhitespace}} - * - * @param {Node} node - * @returns {void} - * @memberof CommentsParser */ processComment(node: Node): void { const { commentStack } = this.state; @@ -158,8 +149,6 @@ export default class CommentsParser extends BaseParser { /** * Assign the comments of comment whitespaces to related AST nodes. * Also adjust innerComments following trailing comma. - * - * @memberof CommentsParser */ finalizeComment(commentWS: CommentWhitespace) { const { comments } = commentWS; @@ -219,8 +208,6 @@ export default class CommentsParser extends BaseParser { * to each comment whitespace. Used only in parseExpression * where the top level AST node is _not_ Program * {@see {@link CommentsParser#finalizeComment}} - * - * @memberof CommentsParser */ finalizeRemainingComments() { const { commentStack } = this.state; @@ -230,6 +217,7 @@ export default class CommentsParser extends BaseParser { this.state.commentStack = []; } + /* eslint-disable no-irregular-whitespace */ /** * Reset previous node trailing comments. Used in object / class * property parsing. We parse `async`, `static`, `set` and `get` @@ -237,17 +225,17 @@ export default class CommentsParser extends BaseParser { * method later. In this case the identifier is not part of the AST and we * should sync the knowledge to commentStacks * - * For example, when parsing */ - // async /* 1 */ function f() {} - /* - * the comment whitespace "* 1 *" has leading node Identifier(async). When - * we see the function token, we create a Function node and mark "* 1 *" as - * inner comments. So "* 1 *" should be detached from the Identifier node. + * For example, when parsing + * ``` + * async /* 1 *​/ function f() {} + * ``` + * the comment whitespace `/* 1 *​/` has leading node Identifier(async). When + * we see the function token, we create a Function node and mark `/* 1 *​/` as + * inner comments. So `/* 1 *​/` should be detached from the Identifier node. * - * @param {N.Node} node the last finished AST node _before_ current token - * @returns - * @memberof CommentsParser + * @param node the last finished AST node _before_ current token */ + /* eslint-enable no-irregular-whitespace */ resetPreviousNodeTrailingComments(node: Node) { const { commentStack } = this.state; const { length } = commentStack; @@ -264,10 +252,6 @@ export default class CommentsParser extends BaseParser { * * This is used to properly attach comments around parenthesized * expressions as leading/trailing comments of the inner expression. - * - * @param {Node} node - * @param {number} start - * @param {number} end */ takeSurroundingComments(node: Node, start: number, end: number) { const { commentStack } = this.state; diff --git a/packages/babel-parser/src/parser/lval.ts b/packages/babel-parser/src/parser/lval.ts index 67b52575d1fd..990eee1e0e05 100644 --- a/packages/babel-parser/src/parser/lval.ts +++ b/packages/babel-parser/src/parser/lval.ts @@ -84,19 +84,18 @@ export default abstract class LValParser extends NodeUtils { /** * Convert existing expression atom to assignable pattern * if possible. Also checks invalid destructuring targets: - - - Parenthesized Destructuring patterns - - RestElement is not the last element - - Missing `=` in assignment pattern - - NOTE: There is a corresponding "isAssignable" method. - When this one is updated, please check if also that one needs to be updated. - - * @param {Node} node The expression atom - * @param {boolean} [isLHS=false] Whether we are parsing a LeftHandSideExpression. - * If isLHS is `true`, the following cases are allowed: `[(a)] = [0]`, `[(a.b)] = [0]` - * If isLHS is `false`, we are in an arrow function parameters list. - * @memberof LValParser + * + * - Parenthesized Destructuring patterns + * - RestElement is not the last element + * - Missing `=` in assignment pattern + * + * NOTE: There is a corresponding "isAssignable" method. + * When this one is updated, please check if also that one needs to be updated. + * + * @param node The expression atom + * @param isLHS Whether we are parsing a LeftHandSideExpression. + * If isLHS is `true`, the following cases are allowed: `[(a)] = [0]`, `[(a.b)] = [0]` + * If isLHS is `false`, we are in an arrow function parameters list. */ toAssignable(node: Node, isLHS: boolean = false): void { let parenthesized = undefined; @@ -108,7 +107,7 @@ export default abstract class LValParser extends NodeUtils { // i.e. `([(a) = []] = []) => {}` // see also `recordArrowParemeterBindingError` signature in packages/babel-parser/src/util/expression-scope.js if (parenthesized.type === "Identifier") { - this.expressionScope.recordArrowParemeterBindingError( + this.expressionScope.recordArrowParameterBindingError( Errors.InvalidParenthesizedAssignment, { at: node }, ); @@ -510,15 +509,14 @@ export default abstract class LValParser extends NodeUtils { * The `string`-only return option is actually just a shorthand for: * `[key: string, parenthesized: false]`. * - * @param {NodeType} type A Node `type` string - * @param {boolean} isUnparenthesizedInAssign + * @param type A Node `type` string + * @param isUnparenthesizedInAssign * Whether the node in question is unparenthesized and its parent * is either an assignment pattern or an assignment expression. - * @param {BindingTypes} binding + * @param binding * The binding operation that is being considered for this potential * LVal. - * @returns { boolean | string | [string, boolean] } - * `true` or `false` if we can immediately determine whether the node + * @returns `true` or `false` if we can immediately determine whether the node * type in question can be treated as an `LVal`. * A `string` key to traverse if we must check this child. * A `[string, boolean]` tuple if we need to check this child and @@ -548,31 +546,30 @@ export default abstract class LValParser extends NodeUtils { /** * Verify that a target expression is an lval (something that can be assigned to). * - * @param {Expression} expression The expression in question to check. - * @param {Object} options A set of options described below. - * @param {LValAncestor} options.in + * @param expression The expression in question to check. + * @param options A set of options described below. + * @param options.in * The relevant ancestor to provide context information for the error * if the check fails. - * @param {BindingTypes} [options.binding=BIND_NONE] + * @param options.binding * The desired binding type. If the given expression is an identifier * and `binding` is not `BIND_NONE`, `checkLVal` will register binding * to the parser scope See also `src/util/scopeflags.js` - * @param {Set|false} [options.checkClashes=false] + * @param options.checkClashes * An optional string set to check if an identifier name is included. * `checkLVal` will add checked identifier name to `checkClashes` It is * used in tracking duplicates in function parameter lists. If it is * false, `checkLVal` will skip duplicate checks - * @param {boolean} [options.allowingSloppyLetBinding] + * @param options.allowingSloppyLetBinding * Whether an identifier named "let" should be allowed in sloppy mode. * Defaults to `true` unless lexical scope its being used. This property * is only relevant if the parser's state is in sloppy mode. - * @param {boolean} [options.strictModeChanged=false] + * @param options.strictModeChanged * Whether an identifier has been parsed in a sloppy context but should * be reinterpreted as strict-mode. e.g. `(arguments) => { "use strict "}` - * @param {boolean} [options.hasParenthesizedAncestor=false] + * @param options.hasParenthesizedAncestor * This is only used internally during recursive calls, and you should * not have to set it yourself. - * @memberof LValParser */ checkLVal( diff --git a/packages/babel-parser/src/parser/statement.ts b/packages/babel-parser/src/parser/statement.ts index 4017819836d6..8b95366f08a4 100644 --- a/packages/babel-parser/src/parser/statement.ts +++ b/packages/babel-parser/src/parser/statement.ts @@ -73,8 +73,6 @@ const keywordRelationalOperator = /in(?:stanceof)?/y; * tt.templateNonTail => tt.backquote/tt.braceR + tt.template + tt.dollarBraceL * For performance reasons this routine mutates `tokens`, it is okay * here since we execute `parseTopLevel` once for every file. - * @param {*} tokens - * @returns */ function babel7CompatTokens(tokens: (Token | N.Comment)[], input: string) { for (let i = 0; i < tokens.length; i++) { @@ -248,14 +246,8 @@ export default abstract class StatementParser extends ExpressionParser { return finishedProgram; } - // TODO - /** * cast a Statement to a Directive. This method mutates input statement. - * - * @param {N.Statement} stmt - * @returns {N.Directive} - * @memberof StatementParser */ stmtToDirective(stmt: N.Statement): N.Directive { const directive = stmt as any; @@ -323,9 +315,6 @@ export default abstract class StatementParser extends ExpressionParser { /** * Assuming we have seen a contextual `let` and declaration is allowed, check if it * starts a variable declaration so that it should be interpreted as a keyword. - * - * @returns {boolean} - * @memberof StatementParser */ hasFollowingBindingAtom(): boolean { const next = this.nextTokenStart(); @@ -339,9 +328,6 @@ export default abstract class StatementParser extends ExpressionParser { /** * Assuming we have seen a contextual `using` and declaration is allowed, check if it * starts a variable declaration so that it should be interpreted as a keyword. - * - * @returns {boolean} - * @memberof StatementParser */ hasFollowingBindingIdentifier(): boolean { const next = this.nextTokenStart(); @@ -2982,9 +2968,7 @@ export default abstract class StatementParser extends ExpressionParser { /** * parse assert entries * - * @see {@link https://tc39.es/proposal-import-assertions/#prod-AssertEntries |AssertEntries} - * @returns {N.ImportAttribute[]} - * @memberof StatementParser + * @see {@link https://tc39.es/proposal-import-assertions/#prod-AssertEntries AssertEntries} */ parseAssertEntries(): N.ImportAttribute[] { const attrs = []; @@ -3031,8 +3015,6 @@ export default abstract class StatementParser extends ExpressionParser { /** * parse module attributes * @deprecated It will be removed in Babel 8 - * @returns - * @memberof StatementParser */ maybeParseModuleAttributes() { if (this.match(tt._with) && !this.hasPrecedingLineBreak()) { diff --git a/packages/babel-parser/src/parser/util.ts b/packages/babel-parser/src/parser/util.ts index 71842067dc72..8c64dfc759e9 100644 --- a/packages/babel-parser/src/parser/util.ts +++ b/packages/babel-parser/src/parser/util.ts @@ -39,8 +39,6 @@ export default abstract class UtilParser extends Tokenizer { // Forward-declaration: defined in parser/index.js abstract getScopeHandler(): { new (...args: any): ScopeHandler }; - // TODO - addExtra( node: Partial, key: string, @@ -128,8 +126,6 @@ export default abstract class UtilParser extends Tokenizer { return skipWhiteSpaceToLineBreak.test(this.input); } - // TODO - isLineTerminator(): boolean { return this.eat(tt.semi) || this.canInsertSemicolon(); } @@ -264,7 +260,7 @@ export default abstract class UtilParser extends Tokenizer { return tokenIsLiteralPropertyName(this.state.type); } - /* + /** * Test if given node is a PrivateName * will be overridden in ESTree plugin */ @@ -272,7 +268,7 @@ export default abstract class UtilParser extends Tokenizer { return node.type === "PrivateName"; } - /* + /** * Return the string value of a given private name * WITHOUT `#` * @see {@link https://tc39.es/ecma262/#sec-static-semantics-stringvalue} @@ -281,7 +277,7 @@ export default abstract class UtilParser extends Tokenizer { return node.id.name; } - /* + /** * Return whether the given node is a member/optional chain that * contains a private name as its property * It is overridden in ESTree plugin @@ -380,7 +376,7 @@ export default abstract class UtilParser extends Tokenizer { * - **shorthandAssignLoc**: track initializer `=` position * - **doubleProtoLoc**: track the duplicate `__proto__` key position * - **privateKey**: track private key `#p` position - * - **optionalParametersLoc**: track the optional paramter (`?`). + * - **optionalParametersLoc**: track the optional parameter (`?`). * It's only used by typescript and flow plugins */ export class ExpressionErrors { diff --git a/packages/babel-parser/src/plugins/placeholders.ts b/packages/babel-parser/src/plugins/placeholders.ts index 11fd8c911ab7..6ba9f23f8c8d 100644 --- a/packages/babel-parser/src/plugins/placeholders.ts +++ b/packages/babel-parser/src/plugins/placeholders.ts @@ -9,7 +9,7 @@ import type { ExpressionErrors } from "../parser/util"; import type { BindingTypes } from "../util/scopeflags"; import type { Position } from "../util/location"; -type PossiblePlaceholedrs = { +type PossiblePlaceholders = { Identifier: N.Identifier; StringLiteral: N.StringLiteral; Expression: N.Expression; @@ -19,9 +19,9 @@ type PossiblePlaceholedrs = { ClassBody: N.ClassBody; Pattern: N.Pattern; }; -export type PlaceholderTypes = keyof PossiblePlaceholedrs; +export type PlaceholderTypes = keyof PossiblePlaceholders; -type NodeOf = PossiblePlaceholedrs[T]; +type NodeOf = PossiblePlaceholders[T]; // todo: when there is proper union type for Node // type NodeOf = Extract; diff --git a/packages/babel-parser/src/plugins/typescript/index.ts b/packages/babel-parser/src/plugins/typescript/index.ts index 89bb31698e11..5c8a0b2ceeb2 100644 --- a/packages/babel-parser/src/plugins/typescript/index.ts +++ b/packages/babel-parser/src/plugins/typescript/index.ts @@ -3541,7 +3541,7 @@ export default (superClass: ClassWithMixin) => case "TSNonNullExpression": case "TSTypeAssertion": if (isLHS) { - this.expressionScope.recordArrowParemeterBindingError( + this.expressionScope.recordArrowParameterBindingError( TSErrors.UnexpectedTypeCastInParameter, { at: node }, ); diff --git a/packages/babel-parser/src/tokenizer/index.ts b/packages/babel-parser/src/tokenizer/index.ts index 5ed7e02f7457..7c3fec7f690d 100644 --- a/packages/babel-parser/src/tokenizer/index.ts +++ b/packages/babel-parser/src/tokenizer/index.ts @@ -119,8 +119,6 @@ export default abstract class Tokenizer extends CommentsParser { this.nextToken(); } - // TODO - eat(type: TokenType): boolean { if (this.match(type)) { this.next(); @@ -132,10 +130,6 @@ export default abstract class Tokenizer extends CommentsParser { /** * Whether current token matches given type - * - * @param {TokenType} type - * @returns {boolean} - * @memberof Tokenizer */ match(type: TokenType): boolean { return this.state.type === type; @@ -143,10 +137,6 @@ export default abstract class Tokenizer extends CommentsParser { /** * Create a LookaheadState from current parser state - * - * @param {State} state - * @returns {LookaheadState} - * @memberof Tokenizer */ createLookaheadState(state: State): LookaheadState { return { @@ -177,9 +167,6 @@ export default abstract class Tokenizer extends CommentsParser { * * The tokenizer should make best efforts to avoid using any parser state * other than those defined in LookaheadState - * - * @returns {LookaheadState} - * @memberof Tokenizer */ lookahead(): LookaheadState { const old = this.state; @@ -1458,11 +1445,6 @@ export default abstract class Tokenizer extends CommentsParser { * * If `errorRecovery` is `true`, the error is pushed to the errors array and * returned. If `errorRecovery` is `false`, the error is instead thrown. - * - * @param {Class>>} ParseErrorClass - * @param {RaiseProperties} raiseProperties - * @returns {(ParseError | empty)} - * @memberof Tokenizer */ raise( toParseError: ParseErrorConstructor, @@ -1484,11 +1466,6 @@ export default abstract class Tokenizer extends CommentsParser { * If `errorRecovery` is `true`, this method will first see if there is * already an error stored at the same `Position`, and replaces it with the * one generated here. - * - * @param {Class>>} ParseErrorClass - * @param {RaiseProperties} raiseProperties - * @returns {(ParseError | empty)} - * @memberof Tokenizer */ raiseOverwrite( toParseError: ParseErrorConstructor, diff --git a/packages/babel-parser/src/util/expression-scope.ts b/packages/babel-parser/src/util/expression-scope.ts index 95200c425703..87d6e4e52fd8 100644 --- a/packages/babel-parser/src/util/expression-scope.ts +++ b/packages/babel-parser/src/util/expression-scope.ts @@ -13,8 +13,8 @@ ExpressionScope is used to track declaration errors in these ambiguous patterns: arrow function parameters until we see an `=>` after `)`. - CoverCallExpressionAndAsyncArrowHead - e.g. we don't know if `async({ x })` is a call expression or an async arrow - function parameters until we see an `=>` after `)` + e.g. we don't know if `async({ x })` is a call expression or an async arrow + function parameters until we see an `=>` after `)` The following declaration errors (@see parser-errors/standard) will be recorded in some expression scopes and thrown later when we know what the ambiguous pattern is @@ -130,9 +130,6 @@ export default class ExpressionScopeHandler { * When current scope is a ParameterDeclaration, the error will be thrown immediately, * otherwise it will be recorded to any ancestry MaybeArrowParameterDeclaration and * MaybeAsyncArrowParameterDeclaration scope until an Expression scope is seen. - * @param {number} pos Error position - * @param {ErrorTemplate} template Error template - * @memberof ExpressionScopeHandler */ recordParameterInitializerError( toParseError: ArrowHeadParsingParameterInitializerError, @@ -177,12 +174,8 @@ export default class ExpressionScopeHandler { * For example, in `( x = ( [(a) = []] = [] ) ) => {}`, we should not record `(a)` in `( x = ... ) =>` * arrow scope because when we finish parsing `( [(a) = []] = [] )`, it is an unambiguous assignment * expression and can not be cast to pattern - * @param {ParseErrorConstructor<{||}>} error - * @param {Node} payload.at - * @returns {void} - * @memberof ExpressionScopeHandler */ - recordArrowParemeterBindingError( + recordArrowParameterBindingError( error: ParseErrorConstructor<{}>, { at: node, @@ -207,9 +200,6 @@ export default class ExpressionScopeHandler { * * Errors will be recorded to any ancestry MaybeAsyncArrowParameterDeclaration * scope until an Expression scope is seen. - * @param {number} pos - * @param {ErrorTemplate} template - * @memberof ExpressionScopeHandler */ recordAsyncArrowParametersError({ at }: { at: Position }): void { const { stack } = this; diff --git a/packages/babel-parser/src/util/location.ts b/packages/babel-parser/src/util/location.ts index 5fa9aa8fd07f..f44ff46cb5bd 100644 --- a/packages/babel-parser/src/util/location.ts +++ b/packages/babel-parser/src/util/location.ts @@ -35,11 +35,6 @@ export class SourceLocation { * This function should be only be used when we create AST node out of the token * boundaries, such as TemplateElement ends before tt.templateNonTail. This * function does not skip whitespaces. - * - * @export - * @param {Position} position - * @param {number} columnOffset - * @returns {Position} */ export function createPositionWithColumnOffset( position: Position,