From 5c1670ca907accd2e725db3f43d1816b992dbdf2 Mon Sep 17 00:00:00 2001
From: Daiki Matoba <telnetstat@gmail.com>
Date: Tue, 23 May 2023 17:26:08 +0900
Subject: [PATCH] chore(packages): add @summary and @deperecated tags to hook
 functions (#837)

* chore(packages): add @summary and @deperecated tags to hook functions

* chore(packages): add JSDoc to useMutation
---
 packages/query/src/index.ts | 16 ++++++++++++----
 packages/swr/src/index.ts   | 10 +++++++++-
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/packages/query/src/index.ts b/packages/query/src/index.ts
index d9ec1b2fc..d4e898ce4 100644
--- a/packages/query/src/index.ts
+++ b/packages/query/src/index.ts
@@ -30,6 +30,7 @@ import {
   Verbs,
   VERBS_WITH_BODY,
   getRouteAsArray,
+  jsDoc,
 } from '@orval/core';
 import omitBy from 'lodash.omitby';
 import {
@@ -698,6 +699,7 @@ const generateQueryImplementation = ({
   route,
   hasVueQueryV4,
   hasSvelteQueryV4,
+  doc,
 }: {
   queryOption: {
     name: string;
@@ -722,6 +724,7 @@ const generateQueryImplementation = ({
   route: string;
   hasVueQueryV4: boolean;
   hasSvelteQueryV4: boolean;
+  doc?: string;
 }) => {
   const queryProps = isVue(outputClient)
     ? vueWrapTypeWithMaybeRef(toObjectString(props, 'implementation'))
@@ -866,7 +869,7 @@ export type ${pascal(
   )}QueryResult = NonNullable<Awaited<ReturnType<${dataType}>>>
 export type ${pascal(name)}QueryError = ${errorType}
 
-export const ${camel(
+${doc}export const ${camel(
     `${operationPrefix}-${name}`,
   )} = <TData = Awaited<ReturnType<${dataType}>>, TError = ${errorType}>(\n ${queryProps} ${queryArguments}\n  ): ${returnType} => {
 
@@ -898,6 +901,8 @@ const generateQueryHook = async (
     mutator,
     response,
     operationId,
+    summary,
+    deprecated,
   }: GeneratorVerbOptions,
   {
     route: _route,
@@ -924,6 +929,8 @@ const generateQueryHook = async (
     OutputClient.SVELTE_QUERY === outputClient &&
     !isSvelteQueryV3(context.packageJson);
 
+  const doc = jsDoc({ summary, deprecated });
+
   if (
     verb === Verbs.GET ||
     operationQueryOptions?.useInfinite ||
@@ -1027,6 +1034,7 @@ const generateQueryHook = async (
           route,
           hasVueQueryV4,
           hasSvelteQueryV4,
+          doc,
         }),
       '',
     )}
@@ -1183,9 +1191,9 @@ ${mutationOptionsFn}
     }
     export type ${pascal(operationName)}MutationError = ${errorType}
 
-    export const ${camel(
-      `${operationPrefix}-${operationName}`,
-    )} = <TError = ${errorType},
+    ${doc}export const ${camel(
+    `${operationPrefix}-${operationName}`,
+  )} = <TError = ${errorType},
     ${!definitions ? `TVariables = void,` : ''}
     TContext = unknown>(${mutationArguments}) => {
     
diff --git a/packages/swr/src/index.ts b/packages/swr/src/index.ts
index 6ec596e83..90b30590d 100644
--- a/packages/swr/src/index.ts
+++ b/packages/swr/src/index.ts
@@ -23,6 +23,7 @@ import {
   toObjectString,
   Verbs,
   VERBS_WITH_BODY,
+  jsDoc,
 } from '@orval/core';
 
 const AXIOS_DEPENDENCIES: GeneratorDependency[] = [
@@ -197,6 +198,7 @@ const generateSwrImplementation = ({
   response,
   swrOptions,
   props,
+  doc,
 }: {
   isRequestOptions: boolean;
   operationName: string;
@@ -208,6 +210,7 @@ const generateSwrImplementation = ({
   response: GetterResponse;
   mutator?: GeneratorMutator;
   swrOptions: { options?: any };
+  doc?: string;
 }) => {
   const swrProps = toObjectString(props, 'implementation');
   const httpFunctionProps = swrProperties;
@@ -233,7 +236,7 @@ export type ${pascal(
   )}QueryResult = NonNullable<Awaited<ReturnType<typeof ${operationName}>>>
 export type ${pascal(operationName)}QueryError = ${errorType}
 
-export const ${camel(
+${doc}export const ${camel(
     `use-${operationName}`,
   )} = <TError = ${errorType}>(\n ${swrProps} ${generateSwrArguments({
     operationName,
@@ -293,6 +296,8 @@ const generateSwrHook = (
     override,
     mutator,
     response,
+    summary,
+    deprecated,
   }: GeneratorVerbOptions,
   { route }: GeneratorOptions,
 ) => {
@@ -321,6 +326,8 @@ const generateSwrHook = (
     'implementation',
   );
 
+  const doc = jsDoc({ summary, deprecated });
+
   return `export const ${swrKeyFnName} = (${queryKeyProps}) => [\`${route}\`${
     queryParams ? ', ...(params ? [params]: [])' : ''
   }${body.implementation ? `, ${body.implementation}` : ''}] as const;
@@ -336,6 +343,7 @@ const generateSwrHook = (
       isRequestOptions,
       response,
       swrOptions: override.swr,
+      doc,
     })}
 `;
 };