docs: indicate return of EspreeTokens from tokenize

Author: brettz9

dist/espree.d.ts

@@ -2,11 +2,11 @@
  * Tokenizes the given code.
  * @param {string} code The code to tokenize.
  * @param {ParserOptions} options Options defining how to tokenize.
- * @returns {import('acorn').Token[]} An array of tokens.
+ * @returns {EspreeTokens} An array of tokens.
  * @throws {import('./lib/espree').EnhancedSyntaxError} If the input code is invalid.
  * @private
  */
-export function tokenize(code: string, options: ParserOptions): import('acorn').Token[];
+export function tokenize(code: string, options: ParserOptions): EspreeTokens;
 /**
  * Parses the given code.
  * @param {string} code The code to tokenize.
@@ -23,6 +23,11 @@ export const Syntax: {
 export const latestEcmaVersion: number;
 export const supportedEcmaVersions: number[];
 export type ecmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 'latest';
+export type EspreeToken = import('./lib/token-translator').EsprimaToken;
+export type EspreeComment = import('./lib/espree').EsprimaComment;
+export type EspreeTokens = {
+    comments?: EspreeComment[];
+} & EspreeToken[];
 export type ParserOptions = {
     allowReserved?: boolean;
     ecmaVersion?: ecmaVersion;

dist/lib/espree.d.ts

@@ -9,39 +9,17 @@ export class EspreeParser extends acorn.Parser {
     constructor(opts: import('../espree').ParserOptions | null, code: string | object);
     /**
      * Returns Espree tokens.
-     * @returns {{comments?: {type: string; value: string; range?: [number, number]; start?: number; end?: number; loc?: {start: import('acorn').Position | undefined; end: import('acorn').Position | undefined}}[]} & import('acorn').Token[] | null} Espree tokens
+     * @returns {import('../espree').EspreeTokens | null} Espree tokens
      */
-    tokenize(): {
-        comments?: {
-            type: string;
-            value: string;
-            range?: [number, number];
-            start?: number;
-            end?: number;
-            loc?: {
-                start: import('acorn').Position | undefined;
-                end: import('acorn').Position | undefined;
-            };
-        }[];
-    } & import('acorn').Token[] | null;
+    tokenize(): import('../espree').EspreeTokens | null;
     /**
      * Parses.
-     * @returns {{sourceType?: "script" | "module" | "commonjs"; comments?: {type: string; value: string; range?: [number, number]; start?: number; end?: number; loc?: {start: import('acorn').Position | undefined; end: import('acorn').Position | undefined}}[]; tokens?: import('acorn').Token[]; body: import('acorn').Node[]} & import('acorn').Node} The program Node
+     * @returns {{sourceType?: "script" | "module" | "commonjs"; comments?: EsprimaComment[]; tokens?: import('../espree').EspreeTokens; body: import('acorn').Node[]} & import('acorn').Node} The program Node
      */
     parse(): {
         sourceType?: "script" | "module" | "commonjs";
-        comments?: {
-            type: string;
-            value: string;
-            range?: [number, number];
-            start?: number;
-            end?: number;
-            loc?: {
-                start: import('acorn').Position | undefined;
-                end: import('acorn').Position | undefined;
-            };
-        }[];
-        tokens?: import('acorn').Token[];
+        comments?: EsprimaComment[];
+        tokens?: import('../espree').EspreeTokens;
         body: import('acorn').Node[];
     } & import('acorn').Node;
     /**
@@ -71,5 +49,16 @@ export type EnhancedSyntaxError = {
 export type EnhancedTokTypes = {
     jsxAttrValueToken?: import('acorn').TokenType;
 } & typeof import('acorn-jsx').tokTypes;
+export type EsprimaComment = {
+    type: string;
+    value: string;
+    range?: [number, number];
+    start?: number;
+    end?: number;
+    loc?: {
+        start: import('acorn').Position | undefined;
+        end: import('acorn').Position | undefined;
+    };
+};
 import * as acorn from "acorn";
 //# sourceMappingURL=espree.d.ts.map

espree.js

@@ -63,6 +63,20 @@
  * @typedef {3|5|6|7|8|9|10|11|12|13|2015|2016|2017|2018|2019|2020|2021|2022|'latest'} ecmaVersion
  */
 
+/**
+ * @typedef {import('./lib/token-translator').EsprimaToken} EspreeToken
+ */
+
+/**
+ * @typedef {import('./lib/espree').EsprimaComment} EspreeComment
+ */
+
+/**
+ * @typedef {{
+ *   comments?: EspreeComment[]
+ * } & EspreeToken[]} EspreeTokens
+ */
+
 /**
  * `jsx.Options` gives us 2 optional properties, so extend it
  *
@@ -182,7 +196,7 @@ const parsers = {
  * Tokenizes the given code.
  * @param {string} code The code to tokenize.
  * @param {ParserOptions} options Options defining how to tokenize.
- * @returns {acorn.Token[]} An array of tokens.
+ * @returns {EspreeTokens} An array of tokens.
  * @throws {EnhancedSyntaxError} If the input code is invalid.
  * @private
  */
@@ -194,7 +208,7 @@ export function tokenize(code, options) {
         options = Object.assign({}, options, { tokens: true }); // eslint-disable-line no-param-reassign
     }
 
-    return /** @type {acorn.Token[]} */ (new Parser(options, code).tokenize());
+    return /** @type {EspreeTokens} */ (new Parser(options, code).tokenize());
 }
 
 //------------------------------------------------------------------------------

lib/espree.js

@@ -51,12 +51,6 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
  */
 
 /**
- *  First three properties as in `acorn.Comment`; next two as in `acorn.Comment`
- *  but optional. Last is different as has to allow `undefined`
- */
-/**
- * @local
- *
  * @typedef {{
  *   type: string,
  *   value: string,
@@ -68,10 +62,16 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
  *     end: acorn.Position | undefined
  *   }
  * }} EsprimaComment
+ */
+
+/**
+ *  First two properties as in `acorn.Comment`; next two as in `acorn.Comment`
+ *  but optional. Last is different as has to allow `undefined`
+ */
+/**
+ * @local
  *
- * @typedef {{
- *   comments?: EsprimaComment[]
- * } & acorn.Token[]} EspreeTokens
+ * @typedef {import('../espree').EspreeTokens} EspreeTokens
  *
  * @typedef {{
  *   tail?: boolean
@@ -98,7 +98,7 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
  * @typedef {{
  *   sourceType?: "script"|"module"|"commonjs";
  *   comments?: EsprimaComment[];
- *   tokens?: acorn.Token[];
+ *   tokens?: EspreeTokens;
  *   body: acorn.Node[];
  * } & acorn.Node} EsprimaProgramNode
  */

lib/token-translator.js

@@ -44,23 +44,21 @@
  * }} BaseEsprimaToken
  *
  * @typedef {{
- *   type: string;
- * } & BaseEsprimaToken} EsprimaToken
- *
- * @typedef {{
- *   type: string | acorn.TokenType;
- * } & BaseEsprimaToken} EsprimaTokenFlexible
- *
- * @typedef {{
  *   jsxAttrValueToken: boolean;
  *   ecmaVersion: ecmaVersion;
  * }} ExtraNoTokens
  *
  * @typedef {{
- *   tokens: EsprimaTokenFlexible[]
+ *   tokens: EsprimaToken[]
  * } & ExtraNoTokens} Extra
  */
 
+/**
+ * @typedef {{
+ *   type: string;
+ * } & BaseEsprimaToken} EsprimaToken
+ */
+
 //------------------------------------------------------------------------------
 // Requirements
 //------------------------------------------------------------------------------
@@ -148,7 +146,7 @@ class TokenTranslator {
     }
 
     /**
-     * Translates a single Esprima token to a single Acorn token. This may be
+     * Translates a single Acorn token to a single Esprima 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 {acorn.Token} token The Acorn token to translate.