Add JSDoc comments generation in $result types and enum declarations (#…

…1277)

.changeset/quick-experts-rest.md

@@ -0,0 +1,5 @@
+---
+'houdini': patch
+---
+
+GraphQL documentation strings and deprecation reasons are reflected as JSDoc comments on generated type definitions. Hover over any field of a query store, an enum, or an enum's value and your IDE should show you the documentation from the GraphQL API.

e2e/_api/schema.graphql

@@ -4,9 +4,14 @@ Date custom scalar type
 scalar DateTime
 scalar File
 
+"""
+Can be Value1 or Value2.
+"""
 enum MyEnum {
+	"The first value"
 	Value1
-	Value2
+	"The second value"
+	Value2 @deprecated(reason: "Use Value1 instead")
 }
 
 enum TypeOfUser {
@@ -15,13 +20,17 @@ enum TypeOfUser {
 }
 
 enum ForceReturn {
+	"Normal"
 	NORMAL
+	"No value"
 	NULL
+	"Some error"
 	ERROR
 }
 
 type Mutation {
 	addUser(
+		"""The users birth date"""
 		birthDate: DateTime!
 		name: String!
 		snapshot: String!
@@ -53,6 +62,9 @@ type Mutation {
 	createB(b: String!): B!
 }
 
+"""
+A node.
+"""
 interface Node {
 	id: ID!
 }
@@ -93,6 +105,9 @@ type Query {
 	rentedBooks: [RentedBook!]!
 	animals: AnimalConnection!
 	monkeys: MonkeyConnection!
+	"""
+	Get a monkey by its id
+	"""
 	monkey(id: ID!): Monkey
 }
 
@@ -105,7 +120,13 @@ type User implements Node {
 	friendsConnection(after: String, before: String, first: Int, last: Int): UserConnection!
 	"This is the same list as what's used globally. its here to tests fragments"
 	usersConnection(after: String, before: String, first: Int, last: Int): UserConnection!
-    usersConnectionSnapshot(after: String, before: String, first: Int, last: Int, snapshot: String!): UserConnection!
+	usersConnectionSnapshot(
+		after: String
+		before: String
+		first: Int
+		last: Int
+		snapshot: String!
+	): UserConnection!
 	"This is the same list as what's used globally. its here to tests fragments"
 	userSearch(filter: UserNameFilter!, snapshot: String!): [User!]!
 	friendsList(limit: Int, offset: Int): [User!]!
@@ -121,10 +142,20 @@ interface Animal implements Node {
 	name: String!
 }
 
+"""
+A monkey.
+"""
 type Monkey implements Node & Animal {
 	id: ID!
 	name: String!
+	"""
+	Whether the monkey has a banana or not
+	"""
 	hasBanana: Boolean!
+	"""
+	Whether the monkey has a banana or not
+	"""
+	oldHasBanana: Boolean @deprecated(reason: "Use hasBanana")
 }
 
 interface AnimalConnection {

packages/houdini/src/codegen/generators/comments/jsdoc.ts

@@ -0,0 +1,10 @@
+import * as recast from 'recast'
+
+const AST = recast.types.builders
+export function jsdocComment(text: string, deprecated?: string) {
+	let commentContent = `*\n * ${text}\n`
+	if (deprecated) {
+		commentContent = `${commentContent} * @deprecated ${deprecated}\n`
+	}
+	return AST.commentBlock(commentContent, true)
+}

packages/houdini/src/codegen/generators/definitions/enums.test.ts

@@ -24,18 +24,24 @@ test('generates runtime definitions for each enum', async function () {
 	expect(parsedQuery).toMatchInlineSnapshot(`
 		type ValuesOf<T> = T[keyof T]
 			
+		/** Documentation of testenum1 */
 		export declare const TestEnum1: {
+		    /** Documentation of Value1 */
 		    readonly Value1: "Value1";
+		    /** Documentation of Value2 */
 		    readonly Value2: "Value2";
 		}
 
+		/** Documentation of testenum1 */
 		export type TestEnum1$options = ValuesOf<typeof TestEnum1>
 		 
+		/** Documentation of testenum2 */
 		export declare const TestEnum2: {
 		    readonly Value3: "Value3";
 		    readonly Value2: "Value2";
 		}
 
+		/** Documentation of testenum2 */
 		export type TestEnum2$options = ValuesOf<typeof TestEnum2>
 	`)
 
@@ -48,11 +54,20 @@ test('generates runtime definitions for each enum', async function () {
 	}).program
 
 	expect(parsedQuery).toMatchInlineSnapshot(`
+		/** Documentation of testenum1 */
 		export const TestEnum1 = {
+		    /**
+		     * Documentation of Value1
+		    */
 		    "Value1": "Value1",
+
+		    /**
+		     * Documentation of Value2
+		    */
 		    "Value2": "Value2"
 		};
 
+		/** Documentation of testenum2 */
 		export const TestEnum2 = {
 		    "Value3": "Value3",
 		    "Value2": "Value2"

packages/houdini/src/codegen/generators/definitions/enums.ts

@@ -4,6 +4,7 @@ import * as recast from 'recast'
 import type { Config } from '../../../lib'
 import { fs, path, printJS } from '../../../lib'
 import { moduleExport } from '../../utils'
+import { jsdocComment } from '../comments/jsdoc'
 
 const AST = recast.types.builders
 
@@ -25,19 +26,39 @@ export default async function definitionsGenerator(config: Config) {
 			enums.map((defn) => {
 				const name = defn.name.value
 
-				return moduleExport(
+				const declaration = moduleExport(
 					config,
 					name,
 					AST.objectExpression(
 						defn.values?.map((value) => {
 							const str = value.name.value
-							return AST.objectProperty(
+							const prop = AST.objectProperty(
 								AST.stringLiteral(str),
 								AST.stringLiteral(str)
 							)
+							const deprecationReason = (
+								value.directives
+									?.find((d) => d.name.value === 'deprecated')
+									?.arguments?.find((a) => a.name.value === 'reason')
+									?.value as graphql.StringValueNode
+							)?.value
+
+							if (value.description || deprecationReason)
+								prop.comments = [
+									jsdocComment(value.description?.value ?? '', deprecationReason),
+								]
+							return prop
 						}) || []
 					)
 				)
+
+				if (defn.description) {
+					declaration.comments = [
+						AST.commentBlock(`* ${defn.description.value} `, true, false),
+					]
+				}
+
+				return declaration
 			})
 		)
 	)
@@ -53,11 +74,22 @@ type ValuesOf<T> = T[keyof T]
 				const name = definition.name.value
 				const values = definition.values
 
-				return `
+				let jsdoc = ''
+				if (definition.description) {
+					jsdoc = `\n/** ${definition.description.value} */`
+				}
+
+				return `${jsdoc}
 export declare const ${name}: {
-${values?.map((value) => `    readonly ${value.name.value}: "${value.name.value}";`).join('\n')}
+${values
+	?.map(
+		(value) =>
+			(value.description ? `    /** ${value.description.value} */\n` : '') +
+			`    readonly ${value.name.value}: "${value.name.value}";`
+	)
+	.join('\n')}
 }
-
+${jsdoc}
 export type ${name}$options = ValuesOf<typeof ${name}>
  `
 			})