chore(tsdoc): enable TSDoc linting (#577)

Author: benjie

.eslintrc.js

@@ -9,7 +9,7 @@ module.exports = {
     "plugin:prettier/recommended",
     "prettier/@typescript-eslint",
   ],
-  plugins: ["jest", "graphql"],
+  plugins: ["jest", "graphql", "tsdoc"],
   env: {
     jest: true,
     node: true,
@@ -42,6 +42,7 @@ module.exports = {
     "no-await-in-loop": 0,
     "jest/no-focused-tests": 2,
     "jest/no-identical-title": 2,
+    "tsdoc/syntax": 2,
 
     // Rules that we should enable:
     "@typescript-eslint/no-use-before-define": "warn",

package.json

@@ -31,6 +31,7 @@
     "eslint-plugin-graphql": "^3.0.3",
     "eslint-plugin-jest": "^22.5.1",
     "eslint-plugin-prettier": "^3.0.1",
+    "eslint-plugin-tsdoc": "^0.2.0",
     "eslint_d": "^8.0.0",
     "graphql": ">=0.9 <0.14 || ^14.0.2",
     "jest": "^24.8.0",

packages/graphile-build-pg/src/plugins/PgConnectionArgOrderBy.ts

@@ -29,7 +29,7 @@ export type OrderBySpec =
        *
        * - true: `NULLS FIRST`
        * - false: `NULLS LAST`
-       * - null: ``
+       * - null: ` `
        */
       boolean | null | undefined
     ];

packages/graphile-build-pg/src/plugins/PgIntrospectionPlugin.ts

@@ -508,8 +508,7 @@ export default (async function PgIntrospectionPlugin(
     );
   };
   /**
-   * @summary introspect database and get the table/view/constraints.
-   * @returns {Promise<PgIntrospectionResultsByKind>}
+   * Introspect database and get the table/view/constraints.
    */
   async function introspect(): Promise<PgIntrospectionResultsByKind> {
     // Perform introspection

packages/graphile-build/src/makeNewBuild.ts

@@ -1105,7 +1105,7 @@ export default function makeNewBuild(builder: SchemaBuilder): BuildBase {
     newWithHooks,
 
     /**
-     * @deprecated
+     * @deprecated Use `fieldDataGeneratorsByFieldNameByType` instead.
      */
     fieldDataGeneratorsByType: fieldDataGeneratorsByFieldNameByType,
 

packages/postgraphile-core/src/index.ts

@@ -86,8 +86,9 @@ export interface PostGraphileCoreOptions {
     build: Build,
     context: TContext
   ) => boolean;
+
   /**
-   * @deprecated Use '@primaryKey' smart comment instead
+   * @deprecated Use '\@primaryKey' smart comment instead
    */
   viewUniqueKey?: string;
   enableTags?: boolean;

yarn.lock

@@ -1586,6 +1586,20 @@
     npmlog "^4.1.2"
     write-file-atomic "^2.3.0"
 
+"@microsoft/[email protected]":
+  version "0.12.16"
+  resolved "https://registry.yarnpkg.com/@microsoft/tsdoc-config/-/tsdoc-config-0.12.16.tgz#88d85b84cbb959ac46fda5037ea71f2e4fe8c598"
+  integrity sha512-oSNFVSwkpE6wa/KFgPI+/hqYhFHcajNmQwA4uczQbhuKkyYYk9dIKKPVNdAFoduwuAX3Yy11vCPKFmhTBWP/8Q==
+  dependencies:
+    "@microsoft/tsdoc" "0.12.16"
+    ajv "~6.10.2"
+    resolve "~1.12.0"
+
+"@microsoft/[email protected]":
+  version "0.12.16"
+  resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.12.16.tgz#13869988581fddbdfdbcb92e26edc955fc6e00ca"
+  integrity sha512-SX8JNEVy6U5+56aQnQB8A2XK+WSF//b0kBa6KqxE48pcccqVuIu1ePAR/EWd1cQB6zWv26QIY5uv/++qm+Z3Mw==
+
 "@mrmlnc/readdir-enhanced@^2.2.1":
   version "2.2.1"
   resolved "https://registry.yarnpkg.com/@mrmlnc/readdir-enhanced/-/readdir-enhanced-2.2.1.tgz#524af240d1a360527b730475ecfa1344aa540dde"
@@ -2060,7 +2074,7 @@ agentkeepalive@^3.4.1:
   dependencies:
     humanize-ms "^1.2.1"
 
-ajv@^6.10.0, ajv@^6.10.2, ajv@^6.5.5:
+ajv@^6.10.0, ajv@^6.10.2, ajv@^6.5.5, ajv@~6.10.2:
   version "6.10.2"
   resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.10.2.tgz#d3cea04d6b017b2894ad69040fec8b623eb4bd52"
   integrity sha512-TXtUUEYHuaTEbLZWIKUr5pmBuhDLy+8KYtPYdcV8qC+pOZL+NKqYwvWSRrVXHn+ZmRRAu8vJTAznH7Oag6RVRw==
@@ -3477,6 +3491,14 @@ eslint-plugin-prettier@^3.0.1:
   dependencies:
     prettier-linter-helpers "^1.0.0"
 
+eslint-plugin-tsdoc@^0.2.0:
+  version "0.2.0"
+  resolved "https://registry.yarnpkg.com/eslint-plugin-tsdoc/-/eslint-plugin-tsdoc-0.2.0.tgz#b31d7a8d1a302a8e1afaa3e3b0f0837461df0a49"
+  integrity sha512-Ciei/N/95nCAqFUhAmN3FNq4r75GtQTFuNBKNOoT1m8OsxhPf+MoD5JJFbvssaaYU0K9jGEjbR/mVyUKg5hWJg==
+  dependencies:
+    "@microsoft/tsdoc" "0.12.16"
+    "@microsoft/tsdoc-config" "0.12.16"
+
 eslint-scope@^4.0.0:
   version "4.0.3"
   resolved "https://registry.yarnpkg.com/eslint-scope/-/eslint-scope-4.0.3.tgz#ca03833310f6889a3264781aa82e63eb9cfe7848"
@@ -7200,6 +7222,13 @@ [email protected], resolve@^1.10.0, resolve@^1.12.0, resolve@^1.3.2, resolve@^1.8.1:
   dependencies:
     path-parse "^1.0.6"
 
+resolve@~1.12.0:
+  version "1.12.3"
+  resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.12.3.tgz#96d5253df8005ce19795c14338f2a013c38a8c15"
+  integrity sha512-hF6+hAPlxjqHWrw4p1rF3Wztbgxd4AjA5VlUzY5zcTb4J8D3JK4/1RjU48pHz2PJWzGVsLB1VWZkvJzhK2CCOA==
+  dependencies:
+    path-parse "^1.0.6"
+
 restore-cursor@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/restore-cursor/-/restore-cursor-2.0.0.tgz#9f7ee287f82fd326d4fd162923d62129eee0dfaf"