diff --git a/package.json b/package.json index a2e0ba565..144f88f42 100644 --- a/package.json +++ b/package.json @@ -63,7 +63,7 @@ "prepublishOnly": "yarn build" }, "devDependencies": { - "@homer0/prettier-plugin-jsdoc": "^4.0.1", + "@homer0/prettier-plugin-jsdoc": "^4.0.5", "@prisma-labs/prettier-config": "0.1.0", "@prisma/client": "2.30.0", "@prisma/sdk": "2.30.0", diff --git a/src/generator/gentime/settingsSingleton.ts b/src/generator/gentime/settingsSingleton.ts index 1bb7f53ee..b23138d16 100644 --- a/src/generator/gentime/settingsSingleton.ts +++ b/src/generator/gentime/settingsSingleton.ts @@ -8,6 +8,36 @@ export namespace Gentime { * @default 'Int' */ projectIdIntToGraphQL?: 'ID' | 'Int' + // TODO once fixed https://github.com/homer0/packages/issues/21 + // use @default tag in this JSDoc block + /** + * Nexus Prisma will project your Prisma schema field/model/enum documentation into JSDoc of the generated Nexus Prisma API. + * + * This setting controls what Nexus Prisma should do when you have not written documentation in your Prisma Schema for a field/model/enum. + * + * The following modes are as follows: + * + * 1. `none` + * + * In this mode, no default JSDoc will be written. + * + * 2. `guide` + * + * In this mode, guide content into your JSDoc that looks something like the following: + * + * ``` + * * ### ️⚠️ You have not writen documentation for ${thisItem} + * + * * Replace this default advisory JSDoc with your own documentation about ${thisItem} + * * by documenting it in your Prisma schema. For example: + * * ... + * * ... + * * ... + * ``` + * + * The default is `guide`. + */ + jsdocPropagationDefault?: 'none' | 'guide' // TODO add some examples /** * Should Prisma Schema docs propagate as docs? @@ -63,6 +93,9 @@ export namespace Gentime { projectIdIntToGraphQL: { initial: () => 'Int', }, + jsdocPropagationDefault: { + initial: () => 'guide', + }, docPropagation: { shorthand: (enabled) => ({ GraphQLDocs: enabled, diff --git a/src/generator/helpers/JSDocTemplates.ts b/src/generator/helpers/JSDocTemplates.ts index 0a7390d0e..3f8d20ffe 100644 --- a/src/generator/helpers/JSDocTemplates.ts +++ b/src/generator/helpers/JSDocTemplates.ts @@ -1,30 +1,35 @@ import { DMMF } from '@prisma/client/runtime' import dedent from 'dindist' import { PrismaDocumentation } from '../../lib/prisma-documnetation' +import { Gentime } from '../gentime/settingsSingleton' type JSDoc = string type FieldModelParams = { field: DMMF.Field model: DMMF.Model + settings: Gentime.Settings } +const jsdocIndent = ' ' +const jsdocEmptyLine = `\n${jsdocIndent}*\n` + /** * Enum */ -export function jsDocForEnum(enum_: DMMF.DatamodelEnum): JSDoc { - return dedent` - /** - ${enumIntro(enum_)} - * - ${nodeDocumentation({ enum: enum_ })} - * - * Contains these members: ${enum_.values.map((value) => value.name).join(', ')} - * - ${enumExample(enum_)} - */ - ` +export function jsDocForEnum(params: { enum: DMMF.DatamodelEnum; settings: Gentime.Settings }): JSDoc { + const sections = [ + enumIntro(params.enum), + nodeDocumentation({ + enum: params.enum, + settings: params.settings, + }), + `* Contains these members: ${params.enum.values.map((value) => value.name).join(', ')}`, + enumExample(params.enum), + ] + const jsdoc = jsDocBookends(joinSections(sections)) + return jsdoc } function enumIntro(enum_: DMMF.DatamodelEnum): string { @@ -44,7 +49,7 @@ function enumExample(enum_: DMMF.DatamodelEnum): string { ` } -function enumMissingDoc(enum_: DMMF.DatamodelEnum): string { +function enumMissingDocGuide(enum_: DMMF.DatamodelEnum): string { return dedent` ${missingDocsIntro({ kind: 'enum', enum: enum_ })} * @@ -63,16 +68,10 @@ function enumMissingDoc(enum_: DMMF.DatamodelEnum): string { * Model */ -export function jsDocForModel(model: DMMF.Model): JSDoc { - return dedent` - /** - ${modelIntro(model)} - * - ${nodeDocumentation({ model })} - * - ${modelExample(model)} - */ - ` +export function jsDocForModel(params: { model: DMMF.Model; settings: Gentime.Settings }): JSDoc { + const sections = [modelIntro(params.model), nodeDocumentation(params), modelExample(params.model)] + const jsdoc = jsDocBookends(joinSections(sections)) + return jsdoc } function modelIntro(model: DMMF.Model): string { @@ -82,8 +81,11 @@ function modelIntro(model: DMMF.Model): string { } const nodeDocumentation = ( - params: { model: DMMF.Model } | { model: DMMF.Model; field: DMMF.Field } | { enum: DMMF.DatamodelEnum } -): string | undefined => { + params: + | { settings: Gentime.Settings; model: DMMF.Model } + | { settings: Gentime.Settings; model: DMMF.Model; field: DMMF.Field } + | { settings: Gentime.Settings; enum: DMMF.DatamodelEnum } +): string | null => { const documentation = 'field' in params ? params.field.documentation @@ -93,18 +95,28 @@ const nodeDocumentation = ( ? params.enum.documentation : null - const doc = documentation - ? `* ${PrismaDocumentation.format(documentation)}` - : 'field' in params - ? fieldMissingDoc({ field: params.field, model: params.model }) - : 'model' in params - ? modelMissingDoc(params.model) - : enumMissingDoc(params.enum) + if (documentation) { + return dedent` + * ${PrismaDocumentation.format(documentation)} + ` + } + + if (params.settings.data.jsdocPropagationDefault === 'guide') { + return 'field' in params + ? fieldMissingDocGuide({ + field: params.field, + model: params.model, + settings: params.settings, + }) + : 'model' in params + ? modelMissingDocGuide(params.model) + : enumMissingDocGuide(params.enum) + } - return doc + return null } -function modelMissingDoc(model: DMMF.Model): string { +function modelMissingDocGuide(model: DMMF.Model): string { // TODO once https://stackoverflow.com/questions/61893953/how-to-escape-symbol-in-jsdoc-for-vscode // is resolved then we can write better examples below like: id String @id return dedent` @@ -142,16 +154,10 @@ function modelExample(model: DMMF.Model): string { * Field */ -export function jsDocForField({ field, model }: FieldModelParams): JSDoc { - return dedent` - /** - ${fieldIntro({ field, model })} - * - ${nodeDocumentation({ field, model })} - * - ${fieldExample({ field, model })} - */ - ` +export function jsDocForField(params: FieldModelParams): JSDoc { + const sections = [fieldIntro(params), nodeDocumentation(params), fieldExample(params)] + const jsdoc = jsDocBookends(joinSections(sections)) + return jsdoc } function fieldIntro({ model, field }: FieldModelParams): string { @@ -160,7 +166,7 @@ function fieldIntro({ model, field }: FieldModelParams): string { ` } -function fieldMissingDoc({ model, field }: FieldModelParams): string { +function fieldMissingDocGuide({ model, field }: FieldModelParams): string { return dedent` ${missingDocsIntro({ kind: 'model', model })} * \`\`\`prisma @@ -210,8 +216,33 @@ function missingDocsIntro( * * Replace this default advisory JSDoc with your own documentation about ${thisItem} * by documenting it in your Prisma schema. For example: - * ` } const missingDocsOutro = `* Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).` + +/** + * Convert a list of JSDoc sections into a single unified JSDoc section. + * + * Each joined section is separated by an empty line. + * + * Each section being joined is expected to handle its own JSDoc "spine" (e.g. `* some content here`). + */ +const joinSections = (sections: (string | null)[]) => { + return sections.filter((section) => section !== null).join(jsdocEmptyLine + jsdocIndent) +} + +const jsDocBookends = (content: string) => { + const start = `/**` + const end = '*/' + const body = prefixBlock(jsdocIndent, content) + + return `${start}\n${body}\n${jsdocIndent}${end}` +} + +const prefixBlock = (prefix: string, content: string): string => { + return content + .split('\n') + .map((_) => `${prefix}${_.trim()}`) + .join('\n') +} diff --git a/src/generator/models/declaration.ts b/src/generator/models/declaration.ts index e1b0dac0a..3f58f74e6 100644 --- a/src/generator/models/declaration.ts +++ b/src/generator/models/declaration.ts @@ -160,7 +160,7 @@ export function renderTypeScriptDeclarationForDocumentModels( } function renderTypeScriptDeclarationForEnum(enum_: DMMF.DatamodelEnum, settings: Gentime.Settings): string { - const jsdoc = settings.data.docPropagation.JSDoc ? jsDocForEnum(enum_) + '\n' : '' + const jsdoc = settings.data.docPropagation.JSDoc ? jsDocForEnum({ enum: enum_, settings }) + '\n' : '' const description = renderPrismaNodeDocumentationToDescription({ settings, node: enum_ }) return dedent` @@ -173,7 +173,7 @@ function renderTypeScriptDeclarationForEnum(enum_: DMMF.DatamodelEnum, settings: } function renderTypeScriptDeclarationForModel(model: DMMF.Model, settings: Gentime.Settings): string { - const jsdoc = settings.data.docPropagation.JSDoc ? jsDocForModel(model) + '\n' : '' + const jsdoc = settings.data.docPropagation.JSDoc ? jsDocForModel({ model, settings }) + '\n' : '' const description = renderPrismaNodeDocumentationToDescription({ settings, node: model }) return dedent` @@ -209,7 +209,7 @@ function renderTypeScriptDeclarationForField({ model: DMMF.Model settings: Gentime.Settings }): string { - const jsdoc = settings.data.docPropagation.JSDoc ? jsDocForField({ field, model }) + '\n' : '' + const jsdoc = settings.data.docPropagation.JSDoc ? jsDocForField({ field, model, settings }) + '\n' : '' const description = renderPrismaNodeDocumentationToDescription({ settings, node: field }) return dedent` ${jsdoc}${field.name}: { diff --git a/tests/__helpers__/testers.ts b/tests/__helpers__/testers.ts index 6fc793f82..4924720ad 100644 --- a/tests/__helpers__/testers.ts +++ b/tests/__helpers__/testers.ts @@ -76,8 +76,19 @@ type IntegrationTestParams = IntegrationTestSpec & { /** * Test that the given Prisma schema generates the expected generated source code. */ -export function testGeneratedModules(params: { databaseSchema: string; description: string }) { +export function testGeneratedModules(params: { + description: string + databaseSchema: string + /** + * The gentime settings to use. + */ + settings?: Gentime.SettingsInput +}) { it(params.description, async () => { + Gentime.settings.reset() + if (params.settings) { + Gentime.settings.change(params.settings) + } const { indexdts } = await generateModules(params.databaseSchema) expect(indexdts).toMatchSnapshot('index.d.ts') }) diff --git a/tests/unit/typescriptDeclarationFile/__snapshots__/enum.test.ts.snap b/tests/unit/typescriptDeclarationFile/__snapshots__/enum.test.ts.snap index 55013e056..0155074bc 100644 --- a/tests/unit/typescriptDeclarationFile/__snapshots__/enum.test.ts.snap +++ b/tests/unit/typescriptDeclarationFile/__snapshots__/enum.test.ts.snap @@ -27,14 +27,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about enum Foo * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * enum Foo { * a * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * Contains these members: a @@ -53,119 +52,6 @@ export interface Foo { } -// -// -// TERMS -// TERMS -// TERMS -// TERMS -// -// - -// -// -// EXPORTS: PRISMA MODELS -// EXPORTS: PRISMA MODELS -// EXPORTS: PRISMA MODELS -// EXPORTS: PRISMA MODELS -// -// - -// N/A –– You have not defined any models in your Prisma schema file. - -// -// -// EXPORTS: PRISMA ENUMS -// EXPORTS: PRISMA ENUMS -// EXPORTS: PRISMA ENUMS -// EXPORTS: PRISMA ENUMS -// -// - -export const Foo: Foo - -// -// -// EXPORTS: OTHER -// EXPORTS: OTHER -// EXPORTS: OTHER -// EXPORTS: OTHER -// -// - -import { Runtime } from '../generator/runtime/settingsSingleton' - -/** - * Adjust Nexus Prisma's [runtime settings](https://pris.ly/nexus-prisma/docs/settings/runtime). - * - * @example - * - * import { PrismaClient } from '@prisma/client' - * import { ApolloServer } from 'apollo-server' - * import { makeSchema } from 'nexus' - * import { User, Post, $settings } from 'nexus-prisma' - * - * new ApolloServer({ - * schema: makeSchema({ - * types: [], - * }), - * context() { - * return { - * db: new PrismaClient(), // <-- You put Prisma client on the \\"db\\" context property - * } - * }, - * }) - * - * $settings({ - * prismaClientContextField: 'db', // <-- Tell Nexus Prisma - * }) - * - * @remarks This is _different_ than Nexus Prisma's [_gentime_ settings](https://pris.ly/nexus-prisma/docs/settings/gentime). - */ -export const $settings: typeof Runtime.changeSettings -" -`; - -exports[`When prisma enum has documentation then it is used for JSDoc and GraphQL enum description: index.d.ts 1`] = ` -"import * as Nexus from 'nexus' -import * as NexusCore from 'nexus/dist/core' - -// -// -// TYPES -// TYPES -// TYPES -// TYPES -// -// - -// Models - -// N/A –– You have not defined any models in your Prisma schema file. - -// Enums - -/** - * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`. - * - * Some documentation - * - * Contains these members: a - * - * @example - * - * import { enumType } from 'nexus' - * import { Foo } from 'nexus-prisma' - * - * enumType(Foo) - */ -export interface Foo { - name: 'Foo' - description: string - members: ['a'] -} - - // // // TERMS diff --git a/tests/unit/typescriptDeclarationFile/__snapshots__/enumDoc.test.ts.snap b/tests/unit/typescriptDeclarationFile/__snapshots__/enumDocumentation.test.ts.snap similarity index 76% rename from tests/unit/typescriptDeclarationFile/__snapshots__/enumDoc.test.ts.snap rename to tests/unit/typescriptDeclarationFile/__snapshots__/enumDocumentation.test.ts.snap index c471d0247..da54056bb 100644 --- a/tests/unit/typescriptDeclarationFile/__snapshots__/enumDoc.test.ts.snap +++ b/tests/unit/typescriptDeclarationFile/__snapshots__/enumDocumentation.test.ts.snap @@ -153,6 +153,117 @@ export interface Foo { } +// +// +// TERMS +// TERMS +// TERMS +// TERMS +// +// + +// +// +// EXPORTS: PRISMA MODELS +// EXPORTS: PRISMA MODELS +// EXPORTS: PRISMA MODELS +// EXPORTS: PRISMA MODELS +// +// + +// N/A –– You have not defined any models in your Prisma schema file. + +// +// +// EXPORTS: PRISMA ENUMS +// EXPORTS: PRISMA ENUMS +// EXPORTS: PRISMA ENUMS +// EXPORTS: PRISMA ENUMS +// +// + +export const Foo: Foo + +// +// +// EXPORTS: OTHER +// EXPORTS: OTHER +// EXPORTS: OTHER +// EXPORTS: OTHER +// +// + +import { Runtime } from '../generator/runtime/settingsSingleton' + +/** + * Adjust Nexus Prisma's [runtime settings](https://pris.ly/nexus-prisma/docs/settings/runtime). + * + * @example + * + * import { PrismaClient } from '@prisma/client' + * import { ApolloServer } from 'apollo-server' + * import { makeSchema } from 'nexus' + * import { User, Post, $settings } from 'nexus-prisma' + * + * new ApolloServer({ + * schema: makeSchema({ + * types: [], + * }), + * context() { + * return { + * db: new PrismaClient(), // <-- You put Prisma client on the \\"db\\" context property + * } + * }, + * }) + * + * $settings({ + * prismaClientContextField: 'db', // <-- Tell Nexus Prisma + * }) + * + * @remarks This is _different_ than Nexus Prisma's [_gentime_ settings](https://pris.ly/nexus-prisma/docs/settings/gentime). + */ +export const $settings: typeof Runtime.changeSettings +" +`; + +exports[`When an enum has no documentation comment, and \`jsdocPropagationDefault\` is set to "none", then it does not get any default JSDoc and its description field is null: index.d.ts 1`] = ` +"import * as Nexus from 'nexus' +import * as NexusCore from 'nexus/dist/core' + +// +// +// TYPES +// TYPES +// TYPES +// TYPES +// +// + +// Models + +// N/A –– You have not defined any models in your Prisma schema file. + +// Enums + +/** + * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`. + * + * Contains these members: a + * + * @example + * + * import { enumType } from 'nexus' + * import { Foo } from 'nexus-prisma' + * + * enumType(Foo) + */ +export interface Foo { + name: 'Foo' + description: undefined + members: ['a'] +} + + // // // TERMS @@ -253,14 +364,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about enum Foo * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * enum Foo { * a * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * Contains these members: a diff --git a/tests/unit/typescriptDeclarationFile/__snapshots__/modelDocumentation.test.ts.snap b/tests/unit/typescriptDeclarationFile/__snapshots__/modelDocumentation.test.ts.snap index b42b22abb..9dfd875d9 100644 --- a/tests/unit/typescriptDeclarationFile/__snapshots__/modelDocumentation.test.ts.snap +++ b/tests/unit/typescriptDeclarationFile/__snapshots__/modelDocumentation.test.ts.snap @@ -31,7 +31,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -52,7 +52,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -180,14 +180,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -201,7 +200,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -222,7 +221,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -350,14 +349,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -371,7 +369,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -383,7 +381,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -404,7 +401,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -540,7 +537,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -552,7 +549,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -573,7 +569,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -701,14 +697,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -722,7 +717,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -734,7 +729,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -755,7 +749,160 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) + */ + id: { + /** + * The name of this field. + */ + name: 'id' + + /** + * The type of this field. + */ + type: 'ID' extends NexusCore.GetGen<'allNamedTypes', string> + ? NexusCore.NexusNonNullDef<'ID'> + : 'Warning/Error: The type \\\\'ID\\\\' is not amoung the union of GetGen<\\\\'allNamedTypes\\\\', string>. This means that either: 1) You need to run nexus typegen reflection. 2) You need to add the type \\\\'ID\\\\' to your GraphQL API.' + + /** + * The documentation of this field. + */ + description: undefined + + /** + * The resolver of this field + */ + resolve: NexusCore.FieldResolver<'SomeModel', 'id'> + } +} + +// Enums + +// N/A –– You have not defined any enums in your Prisma schema file. + + +// +// +// TERMS +// TERMS +// TERMS +// TERMS +// +// + +// +// +// EXPORTS: PRISMA MODELS +// EXPORTS: PRISMA MODELS +// EXPORTS: PRISMA MODELS +// EXPORTS: PRISMA MODELS +// +// + +export const SomeModel: SomeModel + +// +// +// EXPORTS: PRISMA ENUMS +// EXPORTS: PRISMA ENUMS +// EXPORTS: PRISMA ENUMS +// EXPORTS: PRISMA ENUMS +// +// + +// N/A –– You have not defined any enums in your Prisma schema file. + +// +// +// EXPORTS: OTHER +// EXPORTS: OTHER +// EXPORTS: OTHER +// EXPORTS: OTHER +// +// + +import { Runtime } from '../generator/runtime/settingsSingleton' + +/** + * Adjust Nexus Prisma's [runtime settings](https://pris.ly/nexus-prisma/docs/settings/runtime). + * + * @example + * + * import { PrismaClient } from '@prisma/client' + * import { ApolloServer } from 'apollo-server' + * import { makeSchema } from 'nexus' + * import { User, Post, $settings } from 'nexus-prisma' + * + * new ApolloServer({ + * schema: makeSchema({ + * types: [], + * }), + * context() { + * return { + * db: new PrismaClient(), // <-- You put Prisma client on the \\"db\\" context property + * } + * }, + * }) + * + * $settings({ + * prismaClientContextField: 'db', // <-- Tell Nexus Prisma + * }) + * + * @remarks This is _different_ than Nexus Prisma's [_gentime_ settings](https://pris.ly/nexus-prisma/docs/settings/gentime). + */ +export const $settings: typeof Runtime.changeSettings +" +`; + +exports[`When a model or model field has no documentation comment, and \`jsdocPropagationDefault\` is set to "none", then it does not get any default JSDoc and its description field is null: index.d.ts 1`] = ` +"import * as Nexus from 'nexus' +import * as NexusCore from 'nexus/dist/core' + +// +// +// TYPES +// TYPES +// TYPES +// TYPES +// +// + +// Models + +/** + * Generated Nexus \`objectType\` configuration based on your Prisma schema's model \`SomeModel\`. + * + * @example + * + * import { objectType } from 'nexus' + * import { SomeModel } from 'nexus-prisma' + * + * objectType({ + * name: SomeModel.$name + * description: SomeModel.$description + * definition(t) { + * t.field(SomeModel.id) + * } + * }) + */ +export interface SomeModel { + $name: 'SomeModel' + $description: undefined + /** + * Generated Nexus \`t.field\` configuration based on your Prisma schema's model-field \`SomeModel.id\`. + * + * @example + * + * import { objectType } from 'nexus' + * import { SomeModel } from 'nexus-prisma' + * + * objectType({ + * name: SomeModel.$name + * description: SomeModel.$description + * definition(t) { + * t.field(SomeModel.id) + * } + * }) */ id: { /** diff --git a/tests/unit/typescriptDeclarationFile/__snapshots__/modelRelationFields.test.ts.snap b/tests/unit/typescriptDeclarationFile/__snapshots__/modelRelationFields.test.ts.snap index 20f0030b0..2b22feeff 100644 --- a/tests/unit/typescriptDeclarationFile/__snapshots__/modelRelationFields.test.ts.snap +++ b/tests/unit/typescriptDeclarationFile/__snapshots__/modelRelationFields.test.ts.snap @@ -23,14 +23,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model User * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model User { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -44,7 +43,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(User.id) * } - * }) + * }) */ export interface User { $name: 'User' @@ -56,7 +55,6 @@ export interface User { * * Replace this default advisory JSDoc with your own documentation about model User * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model User { * /// Lorem ipsum dolor sit amet. @@ -77,7 +75,7 @@ export interface User { * definition(t) { * t.field(User.id) * } - * }) + * }) */ id: { /** @@ -109,7 +107,6 @@ export interface User { * * Replace this default advisory JSDoc with your own documentation about model User * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model User { * /// Lorem ipsum dolor sit amet. @@ -130,7 +127,7 @@ export interface User { * definition(t) { * t.field(User.posts) * } - * }) + * }) */ posts: { /** @@ -165,14 +162,13 @@ export interface User { * Replace this default advisory JSDoc with your own documentation about model Post * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model Post { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -186,7 +182,7 @@ export interface User { * definition(t) { * t.field(Post.id) * } - * }) + * }) */ export interface Post { $name: 'Post' @@ -198,7 +194,6 @@ export interface Post { * * Replace this default advisory JSDoc with your own documentation about model Post * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model Post { * /// Lorem ipsum dolor sit amet. @@ -219,7 +214,7 @@ export interface Post { * definition(t) { * t.field(Post.id) * } - * }) + * }) */ id: { /** @@ -251,7 +246,6 @@ export interface Post { * * Replace this default advisory JSDoc with your own documentation about model Post * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model Post { * /// Lorem ipsum dolor sit amet. @@ -272,7 +266,7 @@ export interface Post { * definition(t) { * t.field(Post.author) * } - * }) + * }) */ author: { /** @@ -304,7 +298,6 @@ export interface Post { * * Replace this default advisory JSDoc with your own documentation about model Post * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model Post { * /// Lorem ipsum dolor sit amet. @@ -325,7 +318,7 @@ export interface Post { * definition(t) { * t.field(Post.authorId) * } - * }) + * }) */ authorId: { /** diff --git a/tests/unit/typescriptDeclarationFile/__snapshots__/modelScalarFields.test.ts.snap b/tests/unit/typescriptDeclarationFile/__snapshots__/modelScalarFields.test.ts.snap index f4e12e975..d496788d2 100644 --- a/tests/unit/typescriptDeclarationFile/__snapshots__/modelScalarFields.test.ts.snap +++ b/tests/unit/typescriptDeclarationFile/__snapshots__/modelScalarFields.test.ts.snap @@ -23,14 +23,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -44,7 +43,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -56,7 +55,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -77,7 +75,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -109,7 +107,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -130,7 +127,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.foo) * } - * }) + * }) */ foo: { /** @@ -258,14 +255,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -279,7 +275,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -291,7 +287,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -312,7 +307,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -344,7 +339,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -365,7 +359,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.foo) * } - * }) + * }) */ foo: { /** @@ -493,14 +487,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -514,7 +507,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -526,7 +519,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -547,7 +539,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -579,7 +571,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -600,7 +591,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.foo) * } - * }) + * }) */ foo: { /** @@ -728,14 +719,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -749,7 +739,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -761,7 +751,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -782,7 +771,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -814,7 +803,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -835,7 +823,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.foo) * } - * }) + * }) */ foo: { /** @@ -963,14 +951,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -984,7 +971,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -996,7 +983,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1017,7 +1003,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -1049,7 +1035,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1070,7 +1055,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.foo) * } - * }) + * }) */ foo: { /** @@ -1198,14 +1183,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -1219,7 +1203,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -1231,7 +1215,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1252,7 +1235,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -1284,7 +1267,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1305,7 +1287,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.foo) * } - * }) + * }) */ foo: { /** @@ -1433,14 +1415,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -1454,7 +1435,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -1466,7 +1447,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1487,7 +1467,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -1615,14 +1595,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -1636,7 +1615,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -1648,7 +1627,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1669,7 +1647,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** @@ -1701,7 +1679,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1722,7 +1699,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.foo) * } - * }) + * }) */ foo: { /** @@ -1850,14 +1827,13 @@ import * as NexusCore from 'nexus/dist/core' * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: * - * * \`\`\`prisma * /// Lorem ipsum dolor sit amet... * model SomeModel { * foo String * } * \`\`\` - * + * * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments). * * @example @@ -1871,7 +1847,7 @@ import * as NexusCore from 'nexus/dist/core' * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ export interface SomeModel { $name: 'SomeModel' @@ -1883,7 +1859,6 @@ export interface SomeModel { * * Replace this default advisory JSDoc with your own documentation about model SomeModel * by documenting it in your Prisma schema. For example: - * * \`\`\`prisma * model SomeModel { * /// Lorem ipsum dolor sit amet. @@ -1904,7 +1879,7 @@ export interface SomeModel { * definition(t) { * t.field(SomeModel.id) * } - * }) + * }) */ id: { /** diff --git a/tests/unit/typescriptDeclarationFile/enum.test.ts b/tests/unit/typescriptDeclarationFile/enum.test.ts index 88b165992..17ea8a2ea 100644 --- a/tests/unit/typescriptDeclarationFile/enum.test.ts +++ b/tests/unit/typescriptDeclarationFile/enum.test.ts @@ -9,13 +9,3 @@ testGeneratedModules({ } `, }) - -testGeneratedModules({ - description: 'When prisma enum has documentation then it is used for JSDoc and GraphQL enum description', - databaseSchema: dedent` - /// Some documentation - enum Foo { - a - } - `, -}) diff --git a/tests/unit/typescriptDeclarationFile/enumDoc.test.ts b/tests/unit/typescriptDeclarationFile/enumDocumentation.test.ts similarity index 75% rename from tests/unit/typescriptDeclarationFile/enumDoc.test.ts rename to tests/unit/typescriptDeclarationFile/enumDocumentation.test.ts index 6a329b61a..0e11ddab7 100644 --- a/tests/unit/typescriptDeclarationFile/enumDoc.test.ts +++ b/tests/unit/typescriptDeclarationFile/enumDocumentation.test.ts @@ -11,6 +11,19 @@ testGeneratedModules({ `, }) +testGeneratedModules({ + description: + 'When an enum has no documentation comment, and `jsdocPropagationDefault` is set to "none", then it does not get any default JSDoc and its description field is null', + settings: { + jsdocPropagationDefault: 'none', + }, + databaseSchema: dedent` + enum Foo { + a + } + `, +}) + testGeneratedModules({ description: 'When an enum has a documentation comment, then it is used for the JSDoc of that enum and its $description field', diff --git a/tests/unit/typescriptDeclarationFile/modelDocumentation.test.ts b/tests/unit/typescriptDeclarationFile/modelDocumentation.test.ts index 8046c0f41..124171de5 100644 --- a/tests/unit/typescriptDeclarationFile/modelDocumentation.test.ts +++ b/tests/unit/typescriptDeclarationFile/modelDocumentation.test.ts @@ -20,6 +20,19 @@ testGeneratedModules({ `, }) +testGeneratedModules({ + description: + 'When a model or model field has no documentation comment, and `jsdocPropagationDefault` is set to "none", then it does not get any default JSDoc and its description field is null', + settings: { + jsdocPropagationDefault: 'none', + }, + databaseSchema: ` + model SomeModel { + id String @id + } + `, +}) + testGeneratedModules({ description: 'When a model has a documentation comment, then it is used for the JSDoc of that model and its $description field', diff --git a/yarn.lock b/yarn.lock index 1d74b834d..293074101 100644 --- a/yarn.lock +++ b/yarn.lock @@ -316,12 +316,12 @@ minimatch "^3.0.4" strip-json-comments "^3.1.1" -"@homer0/prettier-plugin-jsdoc@^4.0.1": - version "4.0.1" - resolved "https://registry.yarnpkg.com/@homer0/prettier-plugin-jsdoc/-/prettier-plugin-jsdoc-4.0.1.tgz#d13624c9c8a49e7bc857007ea35c60e75e2e11e2" - integrity sha512-t9q2E+DTNolhXUlra2I5hLnz49yGezbKmejDFx+gvAFNilUD8x+pV2Xi2kebzYsz1ln/q9oqMDd/rNvLmwo1QA== +"@homer0/prettier-plugin-jsdoc@^4.0.5": + version "4.0.5" + resolved "https://registry.yarnpkg.com/@homer0/prettier-plugin-jsdoc/-/prettier-plugin-jsdoc-4.0.5.tgz#f5c1d07362cbf76bc6762fea2e28bf83bf518684" + integrity sha512-1qWAEUJtcpdp5m8rFxGcgX4fYmoU9puxkKAKlwutNhgwH6Lz5ofv4EzhHxq8Jpl3HU+aHLnWtUtN0MnjOdxqbA== dependencies: - comment-parser "^1.1.5" + comment-parser "^1.2.3" prettier "^2.3.2" ramda "0.27.1" @@ -1902,7 +1902,7 @@ commander@^2.19.0: resolved "https://registry.yarnpkg.com/commander/-/commander-2.20.3.tgz#fd485e84c03eb4881c20722ba48035e8531aeb33" integrity sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ== -comment-parser@1.1.5, comment-parser@^1.1.5: +comment-parser@1.1.5, comment-parser@^1.2.3: version "1.1.5" resolved "https://registry.yarnpkg.com/comment-parser/-/comment-parser-1.1.5.tgz#453627ef8f67dbcec44e79a9bd5baa37f0bce9b2" integrity sha512-RePCE4leIhBlmrqiYTvaqEeGYg7qpSl4etaIabKtdOQVi+mSTIBBklGUwIr79GXYnl3LpMwmDw4KeR2stNc6FA==