docs: added jsdoc types to espree

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) {

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;

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
  */

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}
      */

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": [

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
+  }
+}