Skip to content

Commit e06dce6

Browse files
committed
added jsdoc types to espree
1 parent 15942a2 commit e06dce6

File tree

6 files changed

+80
-10
lines changed

6 files changed

+80
-10
lines changed

espree.js

+8-3
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,11 @@ import espreeVersion from "./lib/version.js";
6464
import * as visitorKeys from "eslint-visitor-keys";
6565
import { getLatestEcmaVersion, getSupportedEcmaVersions } from "./lib/options.js";
6666

67+
/**
68+
* @typedef {import("acorn")} acorn
69+
* @typedef {import("./lib/options").ParserOptions} ParserOptions
70+
*/
71+
6772

6873
// To initialize lazily.
6974
const parsers = {
@@ -102,7 +107,7 @@ const parsers = {
102107
/**
103108
* Tokenizes the given code.
104109
* @param {string} code The code to tokenize.
105-
* @param {Object} options Options defining how to tokenize.
110+
* @param {ParserOptions} options Options defining how to tokenize.
106111
* @returns {Token[]} An array of tokens.
107112
* @throws {SyntaxError} If the input code is invalid.
108113
* @private
@@ -125,8 +130,8 @@ export function tokenize(code, options) {
125130
/**
126131
* Parses the given code.
127132
* @param {string} code The code to tokenize.
128-
* @param {Object} options Options defining how to tokenize.
129-
* @returns {ASTNode} The "Program" AST node.
133+
* @param {ParserOptions} options Options defining how to tokenize.
134+
* @returns {acorn.Node} The "Program" AST node.
130135
* @throws {SyntaxError} If the input code is invalid.
131136
*/
132137
export function parse(code, options) {

lib/espree.js

+25-3
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,23 @@ import TokenTranslator from "./token-translator.js";
33
import { normalizeOptions } from "./options.js";
44

55

6+
/**
7+
* @typedef {import("acorn")} acorn
8+
*/
9+
610
const STATE = Symbol("espree's internal state");
711
const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
812

13+
/**
14+
* @typedef {Object} EsprimaComment
15+
* @property {"Block"|"Line"} type Type of the comment, can either be "Block" (multiline) or "Line" (single line).
16+
* @property {string} text Contents of the comment.
17+
* @property {number|undefined} start Start column of a comment.
18+
* @property {number|undefined} end End column of the comment.
19+
* @property {[number, number]|undefined} range The [start, end] range of a comment.
20+
* @property {acorn.Position} startLoc End location of the comment.
21+
* @property {acorn.Position} endLoc End location of the comment.
22+
*/
923

1024
/**
1125
* Converts an Acorn comment to a Esprima comment.
@@ -15,7 +29,7 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
1529
* @param {int} end The index at which the comment ends.
1630
* @param {Location} startLoc The location at which the comment starts.
1731
* @param {Location} endLoc The location at which the comment ends.
18-
* @returns {Object} The comment object.
32+
* @returns {EsprimaComment} The comment object.
1933
* @private
2034
*/
2135
function convertAcornCommentToEsprimaComment(block, text, start, end, startLoc, endLoc) {
@@ -40,7 +54,12 @@ function convertAcornCommentToEsprimaComment(block, text, start, end, startLoc,
4054
return comment;
4155
}
4256

43-
export default () => Parser => {
57+
/**
58+
* Takes an acorn Parser class and returns a new Parser extending from it.
59+
* @param {typeof acorn.Parser} Parser A base acorn parser class.
60+
* @returns {typeof acorn.Parser} An espree parser extending the base acorn parser.
61+
*/
62+
function extendAcornParser(Parser) {
4463
const tokTypes = Object.assign({}, Parser.acorn.tokTypes);
4564

4665
if (Parser.acornJsx) {
@@ -325,4 +344,7 @@ export default () => Parser => {
325344
return result;
326345
}
327346
};
328-
};
347+
348+
}
349+
350+
export default () => extendAcornParser;

lib/options.js

+12-1
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,20 @@ function normalizeSourceType(sourceType = "script") {
8181
throw new Error("Invalid sourceType.");
8282
}
8383

84+
/**
85+
* @typedef {Object} ParserOptions
86+
* @property {boolean} range Whether to include the range information for each node.
87+
* @property {boolean} loc Whether to include the location information for every node.
88+
* @property {boolean} comments Whether to include an array of all comments
89+
* @property {boolean} tokens Whether to include an array of all tokens
90+
* @property {number|"latest"} ecmaVersion The ECMAScript version to use (between 3 and 13, or 2015 and 2022, or "latest").
91+
* @property {boolean} allowReserved Only allowed when `ecmaVersion` is set to 3.
92+
* @property {"script"|"module"|"commonjs"} sourceType The kind of the source string being parsed.
93+
*/
94+
8495
/**
8596
* Normalize parserOptions
86-
* @param {Object} options the parser options to normalize
97+
* @param {ParserOptions} options the parser options to normalize
8798
* @throws {Error} throw an error if found invalid option.
8899
* @returns {Object} normalized options
89100
*/

lib/token-translator.js

+22-3
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,25 @@
1414
// Private
1515
//------------------------------------------------------------------------------
1616

17+
/**
18+
* @typedef {import("acorn")} acorn
19+
*/
20+
21+
/**
22+
* @typedef {Object} Location
23+
* @property {acorn.Position} start The start position.
24+
* @property {acorn.Position} end The end position.
25+
*/
26+
27+
/**
28+
* @typedef {Object} EsprimaToken
29+
* @property {string} type The type of this token.
30+
* @property {string} value The string content of the token.
31+
* @property {Location|undefined} loc Location in source text.
32+
* @property {number|undefined} start start column.
33+
* @property {number|undefined} end end column.
34+
* @property {[number, number]|undefined} range [start, end] range
35+
*/
1736

1837
// Esprima Token Types
1938
const Token = {
@@ -34,7 +53,7 @@ const Token = {
3453

3554
/**
3655
* Converts part of a template into an Esprima token.
37-
* @param {AcornToken[]} tokens The Acorn tokens representing the template.
56+
* @param {acorn.Token[]} tokens The Acorn tokens representing the template.
3857
* @param {string} code The source code.
3958
* @returns {EsprimaToken} The Esprima equivalent of the template token.
4059
* @private
@@ -94,7 +113,7 @@ TokenTranslator.prototype = {
94113
* Translates a single Esprima token to a single Acorn token. This may be
95114
* inaccurate due to how templates are handled differently in Esprima and
96115
* Acorn, but should be accurate for all other tokens.
97-
* @param {AcornToken} token The Acorn token to translate.
116+
* @param {acorn.Token} token The Acorn token to translate.
98117
* @param {Object} extra Espree extra object.
99118
* @returns {EsprimaToken} The Esprima version of the token.
100119
*/
@@ -174,7 +193,7 @@ TokenTranslator.prototype = {
174193

175194
/**
176195
* Function to call during Acorn's onToken handler.
177-
* @param {AcornToken} token The Acorn token.
196+
* @param {acorn.Token} token The Acorn token.
178197
* @param {Object} extra The Espree extra object.
179198
* @returns {void}
180199
*/

package.json

+2
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
"@rollup/plugin-commonjs": "^17.1.0",
4040
"@rollup/plugin-json": "^4.1.0",
4141
"@rollup/plugin-node-resolve": "^11.2.0",
42+
"@types/acorn": "^4.0.6",
4243
"chai": "^4.3.4",
4344
"eslint": "^7.22.0",
4445
"eslint-config-eslint": "^7.0.0",
@@ -55,6 +56,7 @@
5556
"rollup": "^2.41.2",
5657
"shelljs": "^0.3.0",
5758
"shelljs-nodecli": "^0.1.1",
59+
"typescript": "^4.5.4",
5860
"unicode-6.3.0": "^0.7.5"
5961
},
6062
"keywords": [

tsconfig.json

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
// Change this to match your project
3+
"include": ["lib/**/*", "espree.js"],
4+
"compilerOptions": {
5+
"allowJs": true,
6+
"declaration": true,
7+
"emitDeclarationOnly": true,
8+
"outDir": "dist",
9+
"declarationMap": true
10+
}
11+
}

0 commit comments

Comments
 (0)