From 2979012a020cd4ee1e61a905cbfae8aab6aeb23b Mon Sep 17 00:00:00 2001 From: srijan-paul Date: Tue, 18 Jan 2022 16:17:46 +0530 Subject: [PATCH] docs: added jsdoc types to espree --- espree.js | 11 ++++++++--- lib/espree.js | 28 +++++++++++++++++++++++++--- lib/options.js | 13 ++++++++++++- lib/token-translator.js | 25 ++++++++++++++++++++++--- package.json | 2 ++ tsconfig.json | 11 +++++++++++ 6 files changed, 80 insertions(+), 10 deletions(-) create mode 100644 tsconfig.json diff --git a/espree.js b/espree.js index b79c86f2..36e14b51 100644 --- a/espree.js +++ b/espree.js @@ -64,6 +64,11 @@ import espreeVersion from "./lib/version.js"; import * as visitorKeys from "eslint-visitor-keys"; import { getLatestEcmaVersion, getSupportedEcmaVersions } from "./lib/options.js"; +/** + * @typedef {import("acorn")} acorn + * @typedef {import("./lib/options").ParserOptions} ParserOptions + */ + // To initialize lazily. const parsers = { @@ -102,7 +107,7 @@ const parsers = { /** * Tokenizes the given code. * @param {string} code The code to tokenize. - * @param {Object} options Options defining how to tokenize. + * @param {ParserOptions} options Options defining how to tokenize. * @returns {Token[]} An array of tokens. * @throws {SyntaxError} If the input code is invalid. * @private @@ -125,8 +130,8 @@ export function tokenize(code, options) { /** * Parses the given code. * @param {string} code The code to tokenize. - * @param {Object} options Options defining how to tokenize. - * @returns {ASTNode} The "Program" AST node. + * @param {ParserOptions} options Options defining how to tokenize. + * @returns {acorn.Node} The "Program" AST node. * @throws {SyntaxError} If the input code is invalid. */ export function parse(code, options) { diff --git a/lib/espree.js b/lib/espree.js index 786d89fa..0511ed2b 100644 --- a/lib/espree.js +++ b/lib/espree.js @@ -3,9 +3,23 @@ import TokenTranslator from "./token-translator.js"; import { normalizeOptions } from "./options.js"; +/** + * @typedef {import("acorn")} acorn + */ + const STATE = Symbol("espree's internal state"); const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode"); +/** + * @typedef {Object} EsprimaComment + * @property {"Block"|"Line"} type Type of the comment, can either be "Block" (multiline) or "Line" (single line). + * @property {string} text Contents of the comment. + * @property {number|undefined} start Start column of a comment. + * @property {number|undefined} end End column of the comment. + * @property {[number, number]|undefined} range The [start, end] range of a comment. + * @property {acorn.Position} startLoc End location of the comment. + * @property {acorn.Position} endLoc End location of the comment. + */ /** * Converts an Acorn comment to a Esprima comment. @@ -15,7 +29,7 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode"); * @param {int} end The index at which the comment ends. * @param {Location} startLoc The location at which the comment starts. * @param {Location} endLoc The location at which the comment ends. - * @returns {Object} The comment object. + * @returns {EsprimaComment} The comment object. * @private */ function convertAcornCommentToEsprimaComment(block, text, start, end, startLoc, endLoc) { @@ -40,7 +54,12 @@ function convertAcornCommentToEsprimaComment(block, text, start, end, startLoc, return comment; } -export default () => Parser => { +/** + * Takes an acorn Parser class and returns a new Parser extending from it. + * @param {typeof acorn.Parser} Parser A base acorn parser class. + * @returns {typeof acorn.Parser} An espree parser extending the base acorn parser. + */ +function extendAcornParser(Parser) { const tokTypes = Object.assign({}, Parser.acorn.tokTypes); if (Parser.acornJsx) { @@ -325,4 +344,7 @@ export default () => Parser => { return result; } }; -}; + +} + +export default () => extendAcornParser; diff --git a/lib/options.js b/lib/options.js index 87739699..399bc00e 100644 --- a/lib/options.js +++ b/lib/options.js @@ -81,9 +81,20 @@ function normalizeSourceType(sourceType = "script") { throw new Error("Invalid sourceType."); } +/** + * @typedef {Object} ParserOptions + * @property {boolean} range Whether to include the range information for each node. + * @property {boolean} loc Whether to include the location information for every node. + * @property {boolean} comments Whether to include an array of all comments + * @property {boolean} tokens Whether to include an array of all tokens + * @property {number|"latest"} ecmaVersion The ECMAScript version to use (between 3 and 13, or 2015 and 2022, or "latest"). + * @property {boolean} allowReserved Only allowed when `ecmaVersion` is set to 3. + * @property {"script"|"module"|"commonjs"} sourceType The kind of the source string being parsed. + */ + /** * Normalize parserOptions - * @param {Object} options the parser options to normalize + * @param {ParserOptions} options the parser options to normalize * @throws {Error} throw an error if found invalid option. * @returns {Object} normalized options */ diff --git a/lib/token-translator.js b/lib/token-translator.js index 9aa5e22e..e4e58689 100644 --- a/lib/token-translator.js +++ b/lib/token-translator.js @@ -14,6 +14,25 @@ // Private //------------------------------------------------------------------------------ +/** + * @typedef {import("acorn")} acorn + */ + +/** + * @typedef {Object} Location + * @property {acorn.Position} start The start position. + * @property {acorn.Position} end The end position. + */ + +/** + * @typedef {Object} EsprimaToken + * @property {string} type The type of this token. + * @property {string} value The string content of the token. + * @property {Location|undefined} loc Location in source text. + * @property {number|undefined} start start column. + * @property {number|undefined} end end column. + * @property {[number, number]|undefined} range [start, end] range + */ // Esprima Token Types const Token = { @@ -34,7 +53,7 @@ const Token = { /** * Converts part of a template into an Esprima token. - * @param {AcornToken[]} tokens The Acorn tokens representing the template. + * @param {acorn.Token[]} tokens The Acorn tokens representing the template. * @param {string} code The source code. * @returns {EsprimaToken} The Esprima equivalent of the template token. * @private @@ -94,7 +113,7 @@ TokenTranslator.prototype = { * Translates a single Esprima token to a single Acorn token. This may be * inaccurate due to how templates are handled differently in Esprima and * Acorn, but should be accurate for all other tokens. - * @param {AcornToken} token The Acorn token to translate. + * @param {acorn.Token} token The Acorn token to translate. * @param {Object} extra Espree extra object. * @returns {EsprimaToken} The Esprima version of the token. */ @@ -174,7 +193,7 @@ TokenTranslator.prototype = { /** * Function to call during Acorn's onToken handler. - * @param {AcornToken} token The Acorn token. + * @param {acorn.Token} token The Acorn token. * @param {Object} extra The Espree extra object. * @returns {void} */ diff --git a/package.json b/package.json index 99ad8c26..43834e68 100644 --- a/package.json +++ b/package.json @@ -39,6 +39,7 @@ "@rollup/plugin-commonjs": "^17.1.0", "@rollup/plugin-json": "^4.1.0", "@rollup/plugin-node-resolve": "^11.2.0", + "@types/acorn": "^4.0.6", "chai": "^4.3.4", "eslint": "^7.22.0", "eslint-config-eslint": "^7.0.0", @@ -55,6 +56,7 @@ "rollup": "^2.41.2", "shelljs": "^0.3.0", "shelljs-nodecli": "^0.1.1", + "typescript": "^4.5.4", "unicode-6.3.0": "^0.7.5" }, "keywords": [ diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 00000000..4ff1fe3a --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,11 @@ +{ + // Change this to match your project + "include": ["lib/**/*", "espree.js"], + "compilerOptions": { + "allowJs": true, + "declaration": true, + "emitDeclarationOnly": true, + "outDir": "dist", + "declarationMap": true + } +} \ No newline at end of file