build: add eslint-plugin-tsdoc (#3146)

.eslintrc.yml

@@ -449,9 +449,17 @@ overrides:
       project: ['tsconfig.json']
     plugins:
       - '@typescript-eslint'
+      - 'eslint-plugin-tsdoc'
     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.28.x`
       ##########################################################################

package.json

@@ -62,6 +62,7 @@
     "eslint-plugin-internal-rules": "file:./resources/eslint-internal-rules",
     "eslint-plugin-istanbul": "0.1.2",
     "eslint-plugin-node": "11.1.0",
+    "eslint-plugin-tsdoc": "0.2.14",
     "mocha": "9.0.1",
     "nyc": "15.1.0",
     "prettier": "2.3.2",

src/__testUtils__/dedent.ts

@@ -19,12 +19,14 @@ export function dedentString(string: string): string {
  * An ES6 string tag that fixes indentation and also trims string.
  *
  * Example usage:
+ * ```ts
  * const str = dedent`
  *   {
  *     test
  *   }
  * `;
  * str === "{\n  test\n}";
+ * ```
  */
 export function dedent(
   strings: ReadonlyArray<string>,

src/__tests__/starWarsSchema.ts

@@ -27,6 +27,7 @@ import { getFriends, getHero, getHuman, getDroid } from './starWarsData';
  * Using our shorthand to describe type systems, the type system for our
  * Star Wars example is:
  *
+ * ```graphql
  * enum Episode { NEW_HOPE, EMPIRE, JEDI }
  *
  * interface Character {
@@ -57,6 +58,7 @@ import { getFriends, getHero, getHuman, getDroid } from './starWarsData';
  *   human(id: String!): Human
  *   droid(id: String!): Droid
  * }
+ * ```
  *
  * We begin by setting up our schema.
  */
@@ -65,7 +67,9 @@ import { getFriends, getHero, getHuman, getDroid } from './starWarsData';
  * The original trilogy consists of three movies.
  *
  * This implements the following type system shorthand:
- *   enum Episode { NEW_HOPE, EMPIRE, JEDI }
+ * ```graphql
+ * enum Episode { NEW_HOPE, EMPIRE, JEDI }
+ * ```
  */
 const episodeEnum = new GraphQLEnumType({
   name: 'Episode',
@@ -90,13 +94,15 @@ const episodeEnum = new GraphQLEnumType({
  * Characters in the Star Wars trilogy are either humans or droids.
  *
  * This implements the following type system shorthand:
- *   interface Character {
- *     id: String!
- *     name: String
- *     friends: [Character]
- *     appearsIn: [Episode]
- *     secretBackstory: String
- *   }
+ * ```graphql
+ * interface Character {
+ *   id: String!
+ *   name: String
+ *   friends: [Character]
+ *   appearsIn: [Episode]
+ *   secretBackstory: String
+ * }
+ * ```
  */
 const characterInterface: GraphQLInterfaceType = new GraphQLInterfaceType({
   name: 'Character',
@@ -141,13 +147,15 @@ const characterInterface: GraphQLInterfaceType = new GraphQLInterfaceType({
  * We define our human type, which implements the character interface.
  *
  * This implements the following type system shorthand:
- *   type Human : Character {
- *     id: String!
- *     name: String
- *     friends: [Character]
- *     appearsIn: [Episode]
- *     secretBackstory: String
- *   }
+ * ```graphql
+ * type Human : Character {
+ *   id: String!
+ *   name: String
+ *   friends: [Character]
+ *   appearsIn: [Episode]
+ *   secretBackstory: String
+ * }
+ * ```
  */
 const humanType = new GraphQLObjectType({
   name: 'Human',
@@ -190,14 +198,16 @@ const humanType = new GraphQLObjectType({
  * The other type of character in Star Wars is a droid.
  *
  * This implements the following type system shorthand:
- *   type Droid : Character {
- *     id: String!
- *     name: String
- *     friends: [Character]
- *     appearsIn: [Episode]
- *     secretBackstory: String
- *     primaryFunction: String
- *   }
+ * ```graphql
+ * type Droid : Character {
+ *   id: String!
+ *   name: String
+ *   friends: [Character]
+ *   appearsIn: [Episode]
+ *   secretBackstory: String
+ *   primaryFunction: String
+ * }
+ * ```
  */
 const droidType = new GraphQLObjectType({
   name: 'Droid',
@@ -243,12 +253,13 @@ const droidType = new GraphQLObjectType({
  * of the Star Wars trilogy, R2-D2, directly.
  *
  * This implements the following type system shorthand:
- *   type Query {
- *     hero(episode: Episode): Character
- *     human(id: String!): Human
- *     droid(id: String!): Droid
- *   }
- *
+ * ```graphql
+ * type Query {
+ *   hero(episode: Episode): Character
+ *   human(id: String!): Human
+ *   droid(id: String!): Droid
+ * }
+ * ```
  */
 const queryType = new GraphQLObjectType({
   name: 'Query',

src/error/GraphQLError.ts

@@ -15,7 +15,7 @@ import { printLocation, printSourceLocation } from '../language/printLocation';
  */
 export class GraphQLError extends Error {
   /**
-   * An array of { line, column } locations within the source GraphQL document
+   * An array of `{ line, column }` locations within the source GraphQL document
    * which correspond to this error.
    *
    * Errors during validation often contain multiple locations, for example to

src/error/formatError.ts

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

src/execution/collectFields.ts

@@ -106,8 +106,8 @@ export function collectFields(
 }
 
 /**
- * Determines if a field should be included based on the @include and @skip
- * directives, where @skip has higher precedence than @include.
+ * Determines if a field should be included based on the `@include` and `@skip`
+ * directives, where `@skip` has higher precedence than `@include`.
  */
 function shouldIncludeNode(
   variableValues: { [variable: string]: unknown },

src/execution/execute.ts

@@ -71,9 +71,9 @@ import { collectFields } from './collectFields';
  *
  * "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 }`
  */
 
 /**
@@ -201,7 +201,7 @@ export function executeSync(args: ExecutionArgs): ExecutionResult {
 }
 
 /**
- * Given a completed execution context and data, build the { errors, data }
+ * Given a completed execution context and data, build the `{ errors, data }`
  * response defined by the "Response" section of the GraphQL specification.
  */
 function buildResponse(

src/index.ts

@@ -18,8 +18,10 @@
  * You may also import from each sub-directory directly. For example, the
  * following two import statements are equivalent:
  *
- *     import { parse } from 'graphql';
- *     import { parse } from 'graphql/language';
+ * ```ts
+ * import { parse } from 'graphql';
+ * import { parse } from 'graphql/language';
+ * ```
  */
 
 /** The GraphQL.js version info. */

src/jsutils/isIterableObject.ts

@@ -7,12 +7,13 @@
  * TypedArray, etc. but excludes string literals.
  *
  * @example
- *
+ * ```ts
  * isIterableObject([ 1, 2, 3 ]) // true
  * isIterableObject(new Map()) // true
  * isIterableObject('ABC') // false
  * isIterableObject({ key: 'value' }) // false
  * isIterableObject({ length: 1, 0: 'Alpha' }) // false
+ * ```
  */
 export function isIterableObject(
   maybeIterable: any,