review changes

Author: IvanGoncharov

.eslintrc.yml

@@ -453,6 +453,13 @@ overrides:
     extends:
       - plugin:import/typescript
     rules:
+      ##########################################################################
+      # `eslint-plugin-tsdoc` rule list based on `v0.2.x`
+      # https://github.com/microsoft/tsdoc/tree/master/eslint-plugin
+      ##########################################################################
+
+      tsdoc/syntax: error
+
       ##########################################################################
       # `@typescript-eslint/eslint-plugin` rule list based on `v4.25.x`
       ##########################################################################
@@ -615,11 +622,6 @@ overrides:
   - files: 'src/**'
     rules:
       internal-rules/require-to-string-tag: error
-
-      # Validating TS Doc comments. see:
-      # https://tsdoc.org/pages/packages/eslint-plugin-tsdoc/
-      'tsdoc/syntax': error
-
   - files: 'src/**/__*__/**'
     rules:
       internal-rules/require-to-string-tag: off

src/__testUtils__/dedent.ts

@@ -18,7 +18,7 @@ export function dedentString(string: string): string {
 /**
  * An ES6 string tag that fixes indentation and also trims string.
  *
- * Example Usage:
+ * Example usage:
  * ```ts
  * const str = dedent`
  *   {

src/__tests__/starWarsSchema.ts

@@ -59,6 +59,7 @@ import { getFriends, getHero, getHuman, getDroid } from './starWarsData';
  *   droid(id: String!): Droid
  * }
  * ```
+ *
  * We begin by setting up our schema.
  */
 

src/error/formatError.ts

@@ -21,7 +21,7 @@ export function formatError(error: GraphQLError): GraphQLFormattedError {
 }
 
 /**
- * @see {@link https://github.com/graphql/graphql-spec/blob/main/spec/Section%207%20--%20Response.md#errors | Errors}
+ * See: https://spec.graphql.org/draft/#sec-Errors
  */
 export interface GraphQLFormattedError {
   /**

src/execution/execute.ts

@@ -82,9 +82,9 @@ import {
  *
  * "Selections" are the definitions that can appear legally and at
  * single level of the query. These include:
- * 1) field references e.g `"a"`
- * 2) fragment "spreads" e.g. `"...c"`
- * 3) inline fragment "spreads" e.g. `"...on Type { a }"`
+ * 1) field references e.g `a`
+ * 2) fragment "spreads" e.g. `...c`
+ * 3) inline fragment "spreads" e.g. `...on Type { a }`
  */
 
 /**

src/index.ts

@@ -15,8 +15,9 @@
  * This also includes utility functions for operating on GraphQL types and
  * GraphQL documents to facilitate building tools.
  *
- * You may also import from each sub-directory directly.
- * the following two import statements are equivalent:
+ * You may also import from each sub-directory directly. For example, the
+ * following two import statements are equivalent:
+ *
  * ```ts
  * import { parse } from 'graphql';
  * import { parse } from 'graphql/language';

src/jsutils/keyMap.ts

@@ -12,15 +12,19 @@ import type { ObjMap } from './ObjMap';
  *   { name: 'Jenny', num: '867-5309' }
  * ]
  *
- * // { Jon: { name: 'Jon', num: '555-1234' },
- * // Jenny: { name: 'Jenny', num: '867-5309' } }
  * const entriesByName = keyMap(
  *   phoneBook,
  *   entry => entry.name
  * )
  *
- * // { name: 'Jenny', num: '857-6309' }
+ * // {
+ * //   Jon: { name: 'Jon', num: '555-1234' },
+ * //   Jenny: { name: 'Jenny', num: '867-5309' }
+ * // }
+ *
  * const jennyEntry = entriesByName['Jenny']
+ *
+ * // { name: 'Jenny', num: '857-6309' }
  * ```
  */
 export function keyMap<T>(

src/language/lexer.ts

@@ -107,20 +107,22 @@ export function isPunctuatorTokenKind(kind: TokenKindEnum): boolean {
   );
 }
 
-/*
+/**
+ * ```
  * SourceCharacter ::
  *   - U+0009 (Horizontal Tab)
  *   - U+000A (New Line)
  *   - U+000D (Carriage Return)
  *   - U+0020-U+FFFF
+ * ```
  */
 function isSourceCharacter(code: number): boolean {
   return (
     code >= 0x0020 || code === 0x0009 || code === 0x000a || code === 0x000d
   );
 }
 
-/*
+/**
  * Prints the code point (or end of file reference) at a given location in a
  * source for use in error messages.
  *
@@ -143,7 +145,7 @@ function printCodePointAt(lexer: Lexer, location: number): string {
   return `U+${zeroPad}${code.toString(16).toUpperCase()}`;
 }
 
-/*
+/**
  * Create a token with line and column location information.
  */
 function createToken(
@@ -158,7 +160,7 @@ function createToken(
   return new Token(kind, start, end, line, col, value);
 }
 
-/*
+/**
  * Gets the next token from the source starting at the given position.
  *
  * This skips over whitespace until it finds the next lexable token, then lexes
@@ -293,7 +295,7 @@ function readNextToken(lexer: Lexer, start: number): Token {
   return createToken(lexer, TokenKind.EOF, bodyLength, bodyLength);
 }
 
-/*
+/**
  * Reads a comment token from the source file.
  *
  * ```
@@ -332,10 +334,11 @@ function readComment(lexer: Lexer, start: number): Token {
   );
 }
 
-/*
+/**
  * Reads a number token from the source file, either a FloatValue or an IntValue
  * depending on whether a FractionalPart or ExponentPart is encountered.
  *
+ * ```
  * IntValue :: IntegerPart [lookahead != {Digit, `.`, NameStart}]
  *
  * IntegerPart ::
@@ -358,6 +361,7 @@ function readComment(lexer: Lexer, start: number): Token {
  * ExponentIndicator :: one of `e` `E`
  *
  * Sign :: one of + -
+ * ```
  */
 function readNumber(lexer: Lexer, start: number, firstCode: number): Token {
   const body = lexer.source.body;
@@ -431,7 +435,7 @@ function readNumber(lexer: Lexer, start: number, firstCode: number): Token {
   );
 }
 
-/*
+/**
  * Returns the new position in the source after reading one or more digits.
  */
 function readDigits(lexer: Lexer, start: number, firstCode: number): number {
@@ -457,7 +461,7 @@ function readDigits(lexer: Lexer, start: number, firstCode: number): number {
   return position;
 }
 
-/*
+/**
  * Reads a single-quote string token from the source file.
  *
  * ```
@@ -548,7 +552,7 @@ function readEscapedUnicode(lexer: Lexer, position: number): EscapeSequence {
   );
 }
 
-/*
+/**
  * Reads four hexadecimal characters and returns the positive integer that 16bit
  * hexadecimal string represents. For example, "000f" will return 15, and "dead"
  * will return 57005.
@@ -566,7 +570,7 @@ function read16BitHexCode(body: string, position: number): number {
   );
 }
 
-/*
+/**
  * Reads a hexadecimal character and returns its positive integer value (0-15).
  *
  * '0' becomes 0, '9' becomes 9
@@ -585,17 +589,17 @@ function readHexDigit(code: number): number {
     : -1;
 }
 
-/*
+/**
  * | Escaped Character | Code Point | Character Name               |
  * | ----------------- | ---------- | ---------------------------- |
- * | {`"`}             | U+0022     | double quote                 |
- * | {`\`}             | U+005C     | reverse solidus (back slash) |
- * | {`/`}             | U+002F     | solidus (forward slash)      |
- * | {`b`}             | U+0008     | backspace                    |
- * | {`f`}             | U+000C     | form feed                    |
- * | {`n`}             | U+000A     | line feed (new line)         |
- * | {`r`}             | U+000D     | carriage return              |
- * | {`t`}             | U+0009     | horizontal tab               |
+ * | `"`               | U+0022     | double quote                 |
+ * | `\`               | U+005C     | reverse solidus (back slash) |
+ * | `/`               | U+002F     | solidus (forward slash)      |
+ * | `b`               | U+0008     | backspace                    |
+ * | `f`               | U+000C     | form feed                    |
+ * | `n`               | U+000A     | line feed (new line)         |
+ * | `r`               | U+000D     | carriage return              |
+ * | `t`               | U+0009     | horizontal tab               |
  */
 function readEscapedCharacter(lexer: Lexer, position: number): EscapeSequence {
   const body = lexer.source.body;
@@ -628,15 +632,17 @@ function readEscapedCharacter(lexer: Lexer, position: number): EscapeSequence {
   );
 }
 
-/*
+/**
  * Reads a block string token from the source file.
  *
+ * ```
  * StringValue ::
  *   - `"""` BlockStringCharacter* `"""`
  *
  * BlockStringCharacter ::
  *   - SourceCharacter but not `"""` or `\"""`
  *   - `\"""`
+ * ```
  */
 function readBlockString(lexer: Lexer, start: number): Token {
   const body = lexer.source.body;
@@ -707,9 +713,10 @@ function readBlockString(lexer: Lexer, start: number): Token {
   throw syntaxError(lexer.source, position, 'Unterminated string.');
 }
 
-/*
+/**
  * Reads an alphanumeric + underscore name from the source.
  *
+ * ```
  * Name ::
  *   - NameStart NameContinue* [lookahead != NameContinue]
  *
@@ -721,6 +728,7 @@ function readBlockString(lexer: Lexer, start: number): Token {
  *   - Letter
  *   - Digit
  *   - `_`
+ * ```
  */
 function readName(lexer: Lexer, start: number): Token {
   const body = lexer.source.body;
@@ -750,20 +758,24 @@ function isNameStart(code: number): boolean {
   return isLetter(code) || code === 0x005f;
 }
 
-/*
+/**
+ * ```
  * Digit :: one of
  *   - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`
+ * ```
  */
 function isDigit(code: number): boolean {
   return code >= 0x0030 && code <= 0x0039;
 }
 
-/*
+/**
+ * ```
  * Letter :: one of
  *   - `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M`
  *   - `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z`
  *   - `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m`
  *   - `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z`
+ * ```
  */
 function isLetter(code: number): boolean {
   return (

src/language/printer.ts

@@ -316,8 +316,7 @@ function join(
 }
 
 /**
- * Given array, print each item on its own line, wrapped in an
- * indented `"{ }"` block.
+ * Given array, print each item on its own line, wrapped in an indented `{ }` block.
  */
 function block(array: Maybe<ReadonlyArray<string | undefined>>): string {
   return wrap('{\n', indent(join(array, '\n')), '\n}');

src/language/visitor.ts

@@ -178,7 +178,7 @@ export const BREAK: unknown = Object.freeze({});
  * a new version of the AST with the changes applied will be returned from the
  * visit function.
  *
- * ```
+ * ```ts
  * const editedAST = visit(ast, {
  *   enter(node, key, parent, path, ancestors) {
  *     // @return
@@ -198,22 +198,25 @@ export const BREAK: unknown = Object.freeze({});
  *   }
  * });
  * ```
+ *
  * Alternatively to providing enter() and leave() functions, a visitor can
  * instead provide functions named the same as the kinds of AST nodes, or
  * enter/leave visitors at a named key, leading to three permutations of the
  * visitor API:
  *
  * 1) Named visitors triggered when entering a node of a specific kind.
- * ```
+ *
+ * ```ts
  * visit(ast, {
  *   Kind(node) {
  *     // enter the "Kind" node
  *   }
  * })
  * ```
- * 2) Named visitors that trigger upon entering and leaving a node of
- *    a specific kind.
- * ```
+ *
+ * 2) Named visitors that trigger upon entering and leaving a node of a specific kind.
+ *
+ * ```ts
  * visit(ast, {
  *   Kind: {
  *     enter(node) {
@@ -225,8 +228,10 @@ export const BREAK: unknown = Object.freeze({});
  *   }
  * })
  * ```
+ *
  * 3) Generic visitors that trigger upon entering and leaving any node.
- * ```
+ *
+ * ```ts
  * visit(ast, {
  *   enter(node) {
  *     // enter any node