From ad818171e4ce78bc6e6ee1b75562dbc3c150f749 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Thu, 6 Nov 2025 14:40:29 -0500
Subject: [PATCH 1/4] feat(graphql-request): Represent operation descriptions
 as JSDoc

---
 .../typescript/graphql-request/src/visitor.ts |  6 ++-
 .../graphql-request.spec.ts.snap              | 40 ++++++++++++++-----
 .../tests/graphql-request.spec.ts             |  1 +
 3 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/packages/plugins/typescript/graphql-request/src/visitor.ts b/packages/plugins/typescript/graphql-request/src/visitor.ts
index a2afd8559e..0191adb531 100644
--- a/packages/plugins/typescript/graphql-request/src/visitor.ts
+++ b/packages/plugins/typescript/graphql-request/src/visitor.ts
@@ -6,6 +6,7 @@ import {
   DocumentMode,
   getConfigValue,
   indentMultiline,
+  transformComment,
   LoadedFragment,
 } from '@graphql-codegen/visitor-plugin-common';
 import { RawGraphQLRequestPluginConfig } from './config.js';
@@ -116,6 +117,7 @@ export class GraphQLRequestVisitor extends ClientSideBaseVisitor<
       .map(o => {
         const operationType = o.node.operation;
         const operationName = o.node.name.value;
+        const operationDocComment = transformComment(o.node.description);
         const optionalVariables =
           !o.node.variableDefinitions ||
           o.node.variableDefinitions.length === 0 ||
@@ -130,7 +132,7 @@ export class GraphQLRequestVisitor extends ClientSideBaseVisitor<
             docArg = `${docVarName}String`;
             extraVariables.push(`const ${docArg} = print(${docVarName});`);
           }
-          return `${operationName}(variables${optionalVariables ? '?' : ''}: ${
+          return `${operationDocComment}${operationName}(variables${optionalVariables ? '?' : ''}: ${
             o.operationVariablesTypes
           }, requestHeaders?: GraphQLClientRequestHeaders): Promise<{ data: ${
             o.operationResultType
@@ -142,7 +144,7 @@ export class GraphQLRequestVisitor extends ClientSideBaseVisitor<
     }>(${docArg}, variables, {...requestHeaders, ...wrappedRequestHeaders}), '${operationName}', '${operationType}', variables);
 }`;
         }
-        return `${operationName}(variables${optionalVariables ? '?' : ''}: ${
+        return `${operationDocComment}${operationName}(variables${optionalVariables ? '?' : ''}: ${
           o.operationVariablesTypes
         }, requestHeaders?: GraphQLClientRequestHeaders, signal?: RequestInit['signal']): Promise<${o.operationResultType}> {
   return withWrapper((wrappedRequestHeaders) => client.request<${
diff --git a/packages/plugins/typescript/graphql-request/tests/__snapshots__/graphql-request.spec.ts.snap b/packages/plugins/typescript/graphql-request/tests/__snapshots__/graphql-request.spec.ts.snap
index 6fa680a7df..41bc219680 100644
--- a/packages/plugins/typescript/graphql-request/tests/__snapshots__/graphql-request.spec.ts.snap
+++ b/packages/plugins/typescript/graphql-request/tests/__snapshots__/graphql-request.spec.ts.snap
@@ -204,7 +204,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = \`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -245,6 +246,7 @@ const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationTy
 
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders, signal?: RequestInit['signal']): Promise<FeedQuery> {
       return withWrapper((wrappedRequestHeaders) => client.request<FeedQuery>({ document: FeedDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), 'feed', 'query', variables);
     },
@@ -490,7 +492,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -531,6 +534,7 @@ const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationTy
 
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders, signal?: RequestInit['signal']): Promise<FeedQuery> {
       return withWrapper((wrappedRequestHeaders) => client.request<FeedQuery>({ document: FeedDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), 'feed', 'query', variables);
     },
@@ -768,7 +772,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = \`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -809,6 +814,7 @@ const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationTy
 
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders, signal?: RequestInit['signal']): Promise<FeedQuery> {
       return withWrapper((wrappedRequestHeaders) => client.request<FeedQuery>({ document: FeedDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), 'feed', 'query', variables);
     },
@@ -1048,7 +1054,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -1092,6 +1099,7 @@ const Feed3DocumentString = print(Feed3Document);
 const Feed4DocumentString = print(Feed4Document);
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders): Promise<{ data: FeedQuery; errors?: GraphQLError[]; extensions?: any; headers: Headers; status: number; }> {
         return withWrapper((wrappedRequestHeaders) => client.rawRequest<FeedQuery>(FeedDocumentString, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'feed', 'query', variables);
     },
@@ -1331,7 +1339,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = \`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -1372,6 +1381,7 @@ const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationTy
 
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders): Promise<{ data: FeedQuery; errors?: GraphQLError[]; extensions?: any; headers: Headers; status: number; }> {
         return withWrapper((wrappedRequestHeaders) => client.rawRequest<FeedQuery>(FeedDocument, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'feed', 'query', variables);
     },
@@ -1611,7 +1621,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -1652,6 +1663,7 @@ const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationTy
 
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders, signal?: RequestInit['signal']): Promise<FeedQuery> {
       return withWrapper((wrappedRequestHeaders) => client.request<FeedQuery>({ document: FeedDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), 'feed', 'query', variables);
     },
@@ -1892,7 +1904,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -1936,6 +1949,7 @@ const Feed3DocumentString = print(Feed3Document);
 const Feed4DocumentString = print(Feed4Document);
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders): Promise<{ data: FeedQuery; errors?: GraphQLError[]; extensions?: unknown; headers: Headers; status: number; }> {
         return withWrapper((wrappedRequestHeaders) => client.rawRequest<FeedQuery>(FeedDocumentString, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'feed', 'query', variables);
     },
@@ -2176,7 +2190,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -2220,6 +2235,7 @@ const Feed3DocumentString = print(Feed3Document);
 const Feed4DocumentString = print(Feed4Document);
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders): Promise<{ data: FeedQuery; errors?: GraphQLError[]; extensions?: any; headers: Headers; status: number; }> {
         return withWrapper((wrappedRequestHeaders) => client.rawRequest<FeedQuery>(FeedDocumentString, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'feed', 'query', variables);
     },
@@ -2459,7 +2475,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -2500,6 +2517,7 @@ const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationTy
 
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders, signal?: RequestInit['signal']): Promise<FeedQuery> {
       return withWrapper((wrappedRequestHeaders) => client.request<FeedQuery>({ document: FeedDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), 'feed', 'query', variables);
     },
@@ -2739,7 +2757,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -2780,6 +2799,7 @@ const defaultWrapper: SdkFunctionWrapper = (action, _operationName, _operationTy
 
 export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = defaultWrapper) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, requestHeaders?: GraphQLClientRequestHeaders, signal?: RequestInit['signal']): Promise<FeedQuery> {
       return withWrapper((wrappedRequestHeaders) => client.request<FeedQuery>({ document: FeedDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), 'feed', 'query', variables);
     },
diff --git a/packages/plugins/typescript/graphql-request/tests/graphql-request.spec.ts b/packages/plugins/typescript/graphql-request/tests/graphql-request.spec.ts
index 6634d8fa56..745dcb3a3f 100644
--- a/packages/plugins/typescript/graphql-request/tests/graphql-request.spec.ts
+++ b/packages/plugins/typescript/graphql-request/tests/graphql-request.spec.ts
@@ -13,6 +13,7 @@ import { plugin } from '../src/index.js';
 describe('graphql-request', () => {
   const schema = buildClientSchema(require('../../../../../dev-test/githunt/schema.json'));
   const basicDoc = parse(/* GraphQL */ `
+    """description (becomes JSDoc)"""
     query feed {
       feed {
         id

From 3cf607940f9a9e7c3b5736b96906b596606c84a6 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Thu, 6 Nov 2025 14:40:29 -0500
Subject: [PATCH 2/4] feat(generic-sdk): Represent operation descriptions as
 JSDoc

---
 .../plugins/typescript/generic-sdk/src/visitor.ts    |  4 +++-
 .../tests/__snapshots__/generic-sdk.spec.ts.snap     | 12 +++++++++---
 .../typescript/generic-sdk/tests/generic-sdk.spec.ts |  1 +
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/packages/plugins/typescript/generic-sdk/src/visitor.ts b/packages/plugins/typescript/generic-sdk/src/visitor.ts
index c05a1b817d..709cf5d4fb 100644
--- a/packages/plugins/typescript/generic-sdk/src/visitor.ts
+++ b/packages/plugins/typescript/generic-sdk/src/visitor.ts
@@ -6,6 +6,7 @@ import {
   DocumentMode,
   getConfigValue,
   indentMultiline,
+  transformComment,
   LoadedFragment,
 } from '@graphql-codegen/visitor-plugin-common';
 import { RawGenericSdkPluginConfig } from './config.js';
@@ -110,6 +111,7 @@ export class GenericSdkVisitor extends ClientSideBaseVisitor<
     const allPossibleActions = this._operationsToInclude
       .map(o => {
         const operationName = o.node.name.value;
+        const operationDocComment = transformComment(o.node.description);
         const optionalVariables =
           !o.node.variableDefinitions ||
           o.node.variableDefinitions.length === 0 ||
@@ -125,7 +127,7 @@ export class GenericSdkVisitor extends ClientSideBaseVisitor<
         const resultData = this.config.rawRequest
           ? `ExecutionResult<${o.operationResultType}, E>`
           : o.operationResultType;
-        return `${operationName}(variables${optionalVariables ? '?' : ''}: ${
+        return `${operationDocComment}${operationName}(variables${optionalVariables ? '?' : ''}: ${
           o.operationVariablesTypes
         }, options?: C): ${returnType}<${resultData}> {
   return requester<${o.operationResultType}, ${
diff --git a/packages/plugins/typescript/generic-sdk/tests/__snapshots__/generic-sdk.spec.ts.snap b/packages/plugins/typescript/generic-sdk/tests/__snapshots__/generic-sdk.spec.ts.snap
index b3009a1487..ac8c280883 100644
--- a/packages/plugins/typescript/generic-sdk/tests/__snapshots__/generic-sdk.spec.ts.snap
+++ b/packages/plugins/typescript/generic-sdk/tests/__snapshots__/generic-sdk.spec.ts.snap
@@ -204,7 +204,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -240,6 +241,7 @@ export const Feed4Document = gql\`
 export type Requester<C = {}> = <R, V>(doc: DocumentNode, vars?: V, options?: C) => Promise<R> | AsyncIterable<R>
 export function getSdk<C>(requester: Requester<C>) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, options?: C): Promise<FeedQuery> {
       return requester<FeedQuery, FeedQueryVariables>(FeedDocument, variables, options) as Promise<FeedQuery>;
     },
@@ -945,7 +947,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = \`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -981,6 +984,7 @@ export const Feed4Document = \`
 export type Requester<C = {}> = <R, V>(doc: string, vars?: V, options?: C) => Promise<R> | AsyncIterable<R>
 export function getSdk<C>(requester: Requester<C>) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, options?: C): Promise<FeedQuery> {
       return requester<FeedQuery, FeedQueryVariables>(FeedDocument, variables, options) as Promise<FeedQuery>;
     },
@@ -1218,7 +1222,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -1254,6 +1259,7 @@ export const Feed4Document = gql\`
 export type Requester<C = {}, E = unknown> = <R, V>(doc: DocumentNode, vars?: V, options?: C) => Promise<ExecutionResult<R, E>> | AsyncIterable<ExecutionResult<R, E>>
 export function getSdk<C, E>(requester: Requester<C, E>) {
   return {
+    /** description (becomes JSDoc) */
     feed(variables?: FeedQueryVariables, options?: C): Promise<ExecutionResult<FeedQuery, E>> {
       return requester<FeedQuery, FeedQueryVariables>(FeedDocument, variables, options) as Promise<ExecutionResult<FeedQuery, E>>;
     },
diff --git a/packages/plugins/typescript/generic-sdk/tests/generic-sdk.spec.ts b/packages/plugins/typescript/generic-sdk/tests/generic-sdk.spec.ts
index 7c7356be79..3e89a0261a 100644
--- a/packages/plugins/typescript/generic-sdk/tests/generic-sdk.spec.ts
+++ b/packages/plugins/typescript/generic-sdk/tests/generic-sdk.spec.ts
@@ -17,6 +17,7 @@ const schema = extendSchema(
   `),
 );
 const basicDoc = parse(/* GraphQL */ `
+  """description (becomes JSDoc)"""
   query feed {
     feed {
       id

From 1e4a80fc49ea79188cd99975a0c1f821f0d69c2e Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Thu, 6 Nov 2025 14:40:29 -0500
Subject: [PATCH 3/4] feat(jit-sdk): Represent operation descriptions as JSDoc

---
 packages/plugins/typescript/jit-sdk/src/visitor.ts        | 4 +++-
 .../jit-sdk/tests/__snapshots__/jit-sdk.spec.ts.snap      | 8 ++++++--
 packages/plugins/typescript/jit-sdk/tests/jit-sdk.spec.ts | 1 +
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/plugins/typescript/jit-sdk/src/visitor.ts b/packages/plugins/typescript/jit-sdk/src/visitor.ts
index 003e27817d..e236e503d7 100644
--- a/packages/plugins/typescript/jit-sdk/src/visitor.ts
+++ b/packages/plugins/typescript/jit-sdk/src/visitor.ts
@@ -5,6 +5,7 @@ import {
   ClientSideBaseVisitor,
   DocumentMode,
   indentMultiline,
+  transformComment,
   LoadedFragment,
 } from '@graphql-codegen/visitor-plugin-common';
 import { RawJitSdkPluginConfig } from './config.js';
@@ -83,6 +84,7 @@ export class JitSdkVisitor extends ClientSideBaseVisitor<
     let hasSubscription = false;
     for (const o of this._operationsToInclude) {
       const operationName = o.node.name.value;
+      const operationDocComment = transformComment(o.node.description);
       const compiledQueryVariableName = `${operationName}Compiled`;
       compiledQueries.push(
         indentMultiline(
@@ -115,7 +117,7 @@ if(!(isCompiledQuery(${compiledQueryVariableName}))) {
       }
       sdkMethods.push(
         indentMultiline(
-          `async ${operationName}(variables${optionalVariables ? '?' : ''}: ${
+          `${operationDocComment}async ${operationName}(variables${optionalVariables ? '?' : ''}: ${
             o.operationVariablesTypes
           }, context?: TOperationContext, root?: TOperationRoot): Promise<${returnType}> {
   const result = await ${compiledQueryVariableName}.${methodName}({
diff --git a/packages/plugins/typescript/jit-sdk/tests/__snapshots__/jit-sdk.spec.ts.snap b/packages/plugins/typescript/jit-sdk/tests/__snapshots__/jit-sdk.spec.ts.snap
index c56bebb34f..38047cf9b7 100644
--- a/packages/plugins/typescript/jit-sdk/tests/__snapshots__/jit-sdk.spec.ts.snap
+++ b/packages/plugins/typescript/jit-sdk/tests/__snapshots__/jit-sdk.spec.ts.snap
@@ -206,7 +206,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = gql\`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -277,6 +278,7 @@ export function getSdk<TGlobalContext = any, TGlobalRoot = any, TOperationContex
     }
 
   return {
+    /** description (becomes JSDoc) */
     async feed(variables?: FeedQueryVariables, context?: TOperationContext, root?: TOperationRoot): Promise<FeedQuery> {
       const result = await feedCompiled.query({
         ...globalRoot,
@@ -991,7 +993,8 @@ export type Feed4QueryVariables = Exact<{
 export type Feed4Query = { __typename?: 'Query', feed?: Array<{ __typename?: 'Entry', id: number } | null> | null };
 
 export const FeedDocument = \`
-    query feed {
+    """description (becomes JSDoc)"""
+query feed {
   feed {
     id
     commentCount
@@ -1062,6 +1065,7 @@ export function getSdk<TGlobalContext = any, TGlobalRoot = any, TOperationContex
     }
 
   return {
+    /** description (becomes JSDoc) */
     async feed(variables?: FeedQueryVariables, context?: TOperationContext, root?: TOperationRoot): Promise<FeedQuery> {
       const result = await feedCompiled.query({
         ...globalRoot,
diff --git a/packages/plugins/typescript/jit-sdk/tests/jit-sdk.spec.ts b/packages/plugins/typescript/jit-sdk/tests/jit-sdk.spec.ts
index 0d69e2ce4f..5dd84b7123 100644
--- a/packages/plugins/typescript/jit-sdk/tests/jit-sdk.spec.ts
+++ b/packages/plugins/typescript/jit-sdk/tests/jit-sdk.spec.ts
@@ -12,6 +12,7 @@ import { plugin } from '../src/index.js';
 
 const schema = buildClientSchema(require('../../../../../dev-test/githunt/schema.json'));
 const basicDoc = parse(/* GraphQL */ `
+  """description (becomes JSDoc)"""
   query feed {
     feed {
       id

From 5a39ec83ea190de119891027fda214deb4a436c8 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Thu, 6 Nov 2025 14:40:29 -0500
Subject: [PATCH 4/4] feat(react-apollo): Represent operation descriptions as
 JSDoc

---
 packages/plugins/typescript/react-apollo/src/visitor.ts       | 4 +++-
 .../typescript/react-apollo/tests/react-apollo.spec.ts        | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/plugins/typescript/react-apollo/src/visitor.ts b/packages/plugins/typescript/react-apollo/src/visitor.ts
index f70d04dac6..b12c769f43 100644
--- a/packages/plugins/typescript/react-apollo/src/visitor.ts
+++ b/packages/plugins/typescript/react-apollo/src/visitor.ts
@@ -7,6 +7,7 @@ import {
   ClientSideBaseVisitor,
   DocumentMode,
   getConfigValue,
+  transformComment,
   LoadedFragment,
   OMIT_TYPE,
 } from '@graphql-codegen/visitor-plugin-common';
@@ -526,10 +527,11 @@ export class ReactApolloVisitor extends ClientSideBaseVisitor<
         suffix: this._getHookSuffix(nodeName, operationType),
         useTypesPrefix: false,
       }) + this.config.hooksSuffix;
+    const operationDocComment = transformComment(node.description);
 
     const optional = hasRequiredVariables(node) ? '' : '?';
 
-    return `export function refetch${operationName}(variables${optional}: ${operationVariablesTypes}) {
+    return `${operationDocComment}export function refetch${operationName}(variables${optional}: ${operationVariablesTypes}) {
       return { query: ${this.getDocumentNodeVariable(
         node,
         documentVariableName,
diff --git a/packages/plugins/typescript/react-apollo/tests/react-apollo.spec.ts b/packages/plugins/typescript/react-apollo/tests/react-apollo.spec.ts
index 5b90a4106f..2219e948f8 100644
--- a/packages/plugins/typescript/react-apollo/tests/react-apollo.spec.ts
+++ b/packages/plugins/typescript/react-apollo/tests/react-apollo.spec.ts
@@ -23,6 +23,7 @@ describe('React Apollo', () => {
   const schema = buildClientSchema(require('../../../../../dev-test/githunt/schema.json'));
 
   const basicDoc = parse(/* GraphQL */ `
+    """description for feed"""
     query test {
       feed {
         id
@@ -917,7 +918,8 @@ query MyFeed {
 
       expect(content.content).toBeSimilarStringTo(`
           export const TestDocument = gql\`
-          query test {
+          """description for feed"""
+      query test {
             feed {
               id
               commentCount