improve autogenerated jsdocs (#8633)

dotansimha · Nov 23, 2022 · 00ddc93 · 00ddc93
1 parent 4e3cfdc
commit 00ddc93
Show file tree

Hide file tree

Showing 9 changed files with 613 additions and 37 deletions.
diff --git a/.changeset/thick-ravens-try.md b/.changeset/thick-ravens-try.md
@@ -0,0 +1,5 @@
+---
+'@graphql-codegen/gql-tag-operations': patch
+---
+
+provide jsdoc comments for better IDE support
diff --git a/dev-test/gql-tag-operations-masking-star-wars/gql/gql.ts b/dev-test/gql-tag-operations-masking-star-wars/gql/gql.ts
@@ -2,21 +2,50 @@
 import * as types from './graphql.js';
 import { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core';
 
+/**
+ * Map of all GraphQL operations in the project.
+ *
+ * This map has several performance disadvantages:
+ * 1. It is not tree-shakeable, so it will include all operations in the project.
+ * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.
+ * 3. It does not support dead code elimination, so it will add unused operations.
+ *
+ * Therefore it is highly recommended to use the babel-plugin for production.
+ */
 const documents = {
   '\n  query HeroDetailsWithFragment($episode: Episode) {\n    hero(episode: $episode) {\n      ...HeroDetails\n    }\n  }\n':
     types.HeroDetailsWithFragmentDocument,
   '\n  fragment HeroDetails on Character {\n    __typename\n    name\n    ... on Human {\n      height\n    }\n    ... on Droid {\n      primaryFunction\n    }\n  }\n':
     types.HeroDetailsFragmentDoc,
 };
 
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  query HeroDetailsWithFragment($episode: Episode) {\n    hero(episode: $episode) {\n      ...HeroDetails\n    }\n  }\n'
 ): typeof documents['\n  query HeroDetailsWithFragment($episode: Episode) {\n    hero(episode: $episode) {\n      ...HeroDetails\n    }\n  }\n'];
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  fragment HeroDetails on Character {\n    __typename\n    name\n    ... on Human {\n      height\n    }\n    ... on Droid {\n      primaryFunction\n    }\n  }\n'
 ): typeof documents['\n  fragment HeroDetails on Character {\n    __typename\n    name\n    ... on Human {\n      height\n    }\n    ... on Droid {\n      primaryFunction\n    }\n  }\n'];
 
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ *
+ *
+ * @example
+ * ```ts
+ * const query = gql(`query GetUser($id: ID!) { user(id: $id) { name } }`);
+ * ```
+ *
+ * The query argument is unknown!
+ * Please regenerate the types.
+ **/
 export function gql(source: string): unknown;
+
 export function gql(source: string) {
   return (documents as any)[source] ?? {};
 }

diff --git a/dev-test/gql-tag-operations-masking/gql/gql.ts b/dev-test/gql-tag-operations-masking/gql/gql.ts
@@ -2,6 +2,16 @@
 import * as types from './graphql.js';
 import { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core';
 
+/**
+ * Map of all GraphQL operations in the project.
+ *
+ * This map has several performance disadvantages:
+ * 1. It is not tree-shakeable, so it will include all operations in the project.
+ * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.
+ * 3. It does not support dead code elimination, so it will add unused operations.
+ *
+ * Therefore it is highly recommended to use the babel-plugin for production.
+ */
 const documents = {
   '\n  fragment TweetFragment on Tweet {\n    id\n    body\n    ...TweetAuthorFragment\n  }\n':
     types.TweetFragmentFragmentDoc,
@@ -12,20 +22,45 @@ const documents = {
   '\n  query TweetAppQuery {\n    ...TweetsFragment\n  }\n': types.TweetAppQueryDocument,
 };
 
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  fragment TweetFragment on Tweet {\n    id\n    body\n    ...TweetAuthorFragment\n  }\n'
 ): typeof documents['\n  fragment TweetFragment on Tweet {\n    id\n    body\n    ...TweetAuthorFragment\n  }\n'];
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  fragment TweetAuthorFragment on Tweet {\n    id\n    author {\n      id\n      username\n    }\n  }\n'
 ): typeof documents['\n  fragment TweetAuthorFragment on Tweet {\n    id\n    author {\n      id\n      username\n    }\n  }\n'];
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  fragment TweetsFragment on Query {\n    Tweets {\n      id\n      ...TweetFragment\n    }\n  }\n'
 ): typeof documents['\n  fragment TweetsFragment on Query {\n    Tweets {\n      id\n      ...TweetFragment\n    }\n  }\n'];
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  query TweetAppQuery {\n    ...TweetsFragment\n  }\n'
 ): typeof documents['\n  query TweetAppQuery {\n    ...TweetsFragment\n  }\n'];
 
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ *
+ *
+ * @example
+ * ```ts
+ * const query = gql(`query GetUser($id: ID!) { user(id: $id) { name } }`);
+ * ```
+ *
+ * The query argument is unknown!
+ * Please regenerate the types.
+ **/
 export function gql(source: string): unknown;
+
 export function gql(source: string) {
   return (documents as any)[source] ?? {};
 }

diff --git a/dev-test/gql-tag-operations-urql/gql/gql.d.ts b/dev-test/gql-tag-operations-urql/gql/gql.d.ts
@@ -2,12 +2,21 @@
 import { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core';
 
 declare module '@urql/core' {
+  /**
+   * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+   */
   export function gql(
     source: '\n  query Foo {\n    Tweets {\n      id\n    }\n  }\n'
   ): typeof import('./graphql.js').FooDocument;
+  /**
+   * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+   */
   export function gql(
     source: '\n  fragment Lel on Tweet {\n    id\n    body\n  }\n'
   ): typeof import('./graphql.js').LelFragmentDoc;
+  /**
+   * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+   */
   export function gql(
     source: '\n  query Bar {\n    Tweets {\n      ...Lel\n    }\n  }\n'
   ): typeof import('./graphql.js').BarDocument;

diff --git a/dev-test/gql-tag-operations/gql/gql.ts b/dev-test/gql-tag-operations/gql/gql.ts
@@ -2,23 +2,55 @@
 import * as types from './graphql.js';
 import { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core';
 
+/**
+ * Map of all GraphQL operations in the project.
+ *
+ * This map has several performance disadvantages:
+ * 1. It is not tree-shakeable, so it will include all operations in the project.
+ * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.
+ * 3. It does not support dead code elimination, so it will add unused operations.
+ *
+ * Therefore it is highly recommended to use the babel-plugin for production.
+ */
 const documents = {
   '\n  query Foo {\n    Tweets {\n      id\n    }\n  }\n': types.FooDocument,
   '\n  fragment Lel on Tweet {\n    id\n    body\n  }\n': types.LelFragmentDoc,
   '\n  query Bar {\n    Tweets {\n      ...Lel\n    }\n  }\n': types.BarDocument,
 };
 
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  query Foo {\n    Tweets {\n      id\n    }\n  }\n'
 ): typeof documents['\n  query Foo {\n    Tweets {\n      id\n    }\n  }\n'];
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  fragment Lel on Tweet {\n    id\n    body\n  }\n'
 ): typeof documents['\n  fragment Lel on Tweet {\n    id\n    body\n  }\n'];
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function gql(
   source: '\n  query Bar {\n    Tweets {\n      ...Lel\n    }\n  }\n'
 ): typeof documents['\n  query Bar {\n    Tweets {\n      ...Lel\n    }\n  }\n'];
 
+/**
+ * The gql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ *
+ *
+ * @example
+ * ```ts
+ * const query = gql(`query GetUser($id: ID!) { user(id: $id) { name } }`);
+ * ```
+ *
+ * The query argument is unknown!
+ * Please regenerate the types.
+ **/
 export function gql(source: string): unknown;
+
 export function gql(source: string) {
   return (documents as any)[source] ?? {};
 }

diff --git a/dev-test/gql-tag-operations/graphql/gql.ts b/dev-test/gql-tag-operations/graphql/gql.ts
@@ -2,23 +2,55 @@
 import * as types from './graphql.js';
 import { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core';
 
+/**
+ * Map of all GraphQL operations in the project.
+ *
+ * This map has several performance disadvantages:
+ * 1. It is not tree-shakeable, so it will include all operations in the project.
+ * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.
+ * 3. It does not support dead code elimination, so it will add unused operations.
+ *
+ * Therefore it is highly recommended to use the babel-plugin for production.
+ */
 const documents = {
   '\n  query Foo {\n    Tweets {\n      id\n    }\n  }\n': types.FooDocument,
   '\n  fragment Lel on Tweet {\n    id\n    body\n  }\n': types.LelFragmentDoc,
   '\n  query Bar {\n    Tweets {\n      ...Lel\n    }\n  }\n': types.BarDocument,
 };
 
+/**
+ * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function graphql(
   source: '\n  query Foo {\n    Tweets {\n      id\n    }\n  }\n'
 ): typeof documents['\n  query Foo {\n    Tweets {\n      id\n    }\n  }\n'];
+/**
+ * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function graphql(
   source: '\n  fragment Lel on Tweet {\n    id\n    body\n  }\n'
 ): typeof documents['\n  fragment Lel on Tweet {\n    id\n    body\n  }\n'];
+/**
+ * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ */
 export function graphql(
   source: '\n  query Bar {\n    Tweets {\n      ...Lel\n    }\n  }\n'
 ): typeof documents['\n  query Bar {\n    Tweets {\n      ...Lel\n    }\n  }\n'];
 
+/**
+ * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
+ *
+ *
+ * @example
+ * ```ts
+ * const query = gql(`query GetUser($id: ID!) { user(id: $id) { name } }`);
+ * ```
+ *
+ * The query argument is unknown!
+ * Please regenerate the types.
+ **/
 export function graphql(source: string): unknown;
+
 export function graphql(source: string) {
   return (documents as any)[source] ?? {};
 }

diff --git a/packages/plugins/typescript/gql-tag-operations/src/index.ts b/packages/plugins/typescript/gql-tag-operations/src/index.ts
@@ -57,15 +57,23 @@ export const plugin: PluginFunction<{
     code.push(
       [
         `\n`,
+        `/**\n * The ${gqlTagName} function is used to parse GraphQL queries into a document that can be used by GraphQL clients.\n *\n`,
+        ` *\n * @example\n`,
+        ' * ```ts\n',
+        ' * const query = gql(`query GetUser($id: ID!) { user(id: $id) { name } }`);\n',
+        ' * ```\n *\n',
+        ` * The query argument is unknown!\n`,
+        ` * Please regenerate the types.\n`,
+        `**/\n`,
         `export function ${gqlTagName}(source: string): unknown;\n`,
+        `\n`,
         `export function ${gqlTagName}(source: string) {\n`,
         `  return (documents as any)[source] ?? {};\n`,
         `}\n`,
         `\n`,
         ...documentTypePartial,
       ].join('')
     );
-
     return code.join('');
   }
 
@@ -89,6 +97,13 @@ export const plugin: PluginFunction<{
 
 function getDocumentRegistryChunk(sourcesWithOperations: Array<SourceWithOperations> = []) {
   const lines = new Set<string>();
+  lines.add(
+    `/**\n * Map of all GraphQL operations in the project.\n *\n * This map has several performance disadvantages:\n`
+  );
+  lines.add(` * 1. It is not tree-shakeable, so it will include all operations in the project.\n`);
+  lines.add(` * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.\n`);
+  lines.add(` * 3. It does not support dead code elimination, so it will add unused operations.\n *\n`);
+  lines.add(` * Therefore it is highly recommended to use the babel-plugin for production.\n */\n`);
   lines.add(`const documents = {\n`);
 
   for (const { operations, ...rest } of sourcesWithOperations) {
@@ -123,7 +138,10 @@ function getGqlOverloadChunk(
         : emitLegacyCommonJSImports
         ? `typeof import('./graphql').${operations[0].initialName}`
         : `typeof import('./graphql.js').${operations[0].initialName}`;
-    lines.add(`export function ${gqlTagName}(source: ${JSON.stringify(originalString)}): ${returnType};\n`);
+    lines.add(
+      `/**\n * The ${gqlTagName} function is used to parse GraphQL queries into a document that can be used by GraphQL clients.\n */\n` +
+        `export function ${gqlTagName}(source: ${JSON.stringify(originalString)}): ${returnType};\n`
+    );
   }
 
   return lines;