docs: list enum members in jsdoc (#92)

README.md

@@ -761,6 +761,8 @@ type User {
 
 #### As JSDoc
 
+Can be disabled in [gentime settings](https://pris.ly/nexus-prisma/docs/settings/gentime).
+
 ```prisma
 /// A user.
 model User {
@@ -780,9 +782,10 @@ User.id // JSDoc: A stable identifier to find users by.
 
 These are finer points that aren't perhaps worth a top-level point but none the less add up toward a thoughtful developer experience.
 
-##### Default JSDoc
+##### JSDoc
 
-Fields and models that you do not document will result in a helpful default JSDoc that teaches you about this.
+- Generated Nexus configuration for fields and models that you _have not_ documented in your PSL get default JSDoc that teaches you how to do so.
+- JSDoc for Enums have their members embedded
 
 ##### Default Runtime
 

src/generator/helpers/JSDocTemplates.ts

@@ -1,6 +1,5 @@
 import { DMMF } from '@prisma/client/runtime'
 import dedent from 'dindist'
-import { upperFirst } from 'lodash'
 
 type JSDoc = string
 
@@ -21,14 +20,16 @@ export function jsDocForEnum(enum_: DMMF.DatamodelEnum): JSDoc {
       *
       ${enumDoc}
       *
+      * Contains these members: ${enum_.values.map((value) => value.name).join(', ')}
+      *
       ${enumExample(enum_)}
       */
   `
 }
 
 function enumIntro(enum_: DMMF.DatamodelEnum): string {
   return dedent`
-    * Nexus \`enumType\` configuration based on the \`${enum_.name}\` enum in your Prisma schema.
+    * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`${enum_.name}\`.
   `
 }
 
@@ -45,7 +46,7 @@ function enumExample(enum_: DMMF.DatamodelEnum): string {
 
 function enumMissingDoc(enum_: DMMF.DatamodelEnum): string {
   return dedent`
-    ${missingDocsIntro('enum')}
+    ${missingDocsIntro({ kind: 'enum', enum: enum_ })}
     *
     * \`\`\`prisma
     * /// Lorem ipsum dolor sit amet...
@@ -77,15 +78,15 @@ export function jsDocForModel(model: DMMF.Model): JSDoc {
 
 function modelIntro(model: DMMF.Model): string {
   return dedent`
-    * Nexus \`objectType\` related configuration based on the \`${model.name}\` model in your Prisma schema.
+    * Generated Nexus \`objectType\` configuration based on your Prisma schema's model \`${model.name}\`.
   `
 }
 
 function modelMissingDoc(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`
-    ${missingDocsIntro('model')}
+    ${missingDocsIntro({ kind: 'model', model })}
     * 
     * \`\`\`prisma
     * /// Lorem ipsum dolor sit amet...
@@ -134,13 +135,13 @@ export function jsDocForField({ field, model }: FieldModelParams): JSDoc {
 
 function fieldIntro({ model, field }: FieldModelParams): string {
   return dedent`
-    * Nexus \`t.field\` related configuration based on the \`${model.name}.${field.name}\` field in your Prisma schema.
+    * Generated Nexus \`t.field\` configuration based on your Prisma schema's model-field \`${model.name}.${field.name}\`.
   `
 }
 
 function fieldMissingDoc({ model, field }: FieldModelParams): string {
   return dedent`
-    ${missingDocsIntro('model')}
+    ${missingDocsIntro({ kind: 'model', model })}
     * \`\`\`prisma
     * model ${model.name} {
     *   /// Lorem ipsum dolor sit amet.
@@ -173,14 +174,23 @@ function fieldExample({ model, field }: FieldModelParams): string {
  * Helpers
  */
 
-function missingDocsIntro(kind: 'model' | 'enum' | 'field'): string {
+function missingDocsIntro(
+  info: { kind: 'model'; model: DMMF.Model } | { kind: 'enum'; enum: DMMF.DatamodelEnum } | { kind: 'field' }
+): string {
+  const thisItem =
+    info.kind === 'enum'
+      ? `enum ${info.enum.name}`
+      : info.kind === 'model'
+      ? `model ${info.model.name}`
+      : info.kind
+
   return dedent`
-     * ### ️⚠️ Missing Documentation for this ${upperFirst(kind)}
+     * ### ️⚠️ You have not writen documentation for ${thisItem}
      * 
-     * Automatically ✨ enrich this JSDoc with information about your enum
-     * type by documenting it in your Prisma schema. For example:
+     * 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 Prisma Schema documentation comments [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).`
+const missingDocsOutro = `* Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).`

tests/unit/typescriptDeclarationFile/__snapshots__/enum.test.ts.snap

@@ -21,12 +21,12 @@ declare namespace $Types {
   // Enums
 
   /**
-    * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+    * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
     *
-    * ### ️⚠️ Missing Documentation for this Enum
+    * ### ️⚠️ You have not writen documentation for enum Foo
     * 
-    * Automatically ✨ enrich this JSDoc with information about your enum
-    * type by documenting it in your Prisma schema. For example:
+    * Replace this default advisory JSDoc with your own documentation about enum Foo
+    * by documenting it in your Prisma schema. For example:
     *
     *
     * \`\`\`prisma
@@ -36,7 +36,9 @@ declare namespace $Types {
     * }
     * \`\`\`
     * 
-    * Learn more about Prisma Schema documentation comments [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+    * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+    *
+    * Contains these members: a
     *
     * @example
     *
@@ -83,12 +85,12 @@ declare namespace $Types {
 //
 
 /**
-  * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+  * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
   *
-  * ### ️⚠️ Missing Documentation for this Enum
+  * ### ️⚠️ You have not writen documentation for enum Foo
   * 
-  * Automatically ✨ enrich this JSDoc with information about your enum
-  * type by documenting it in your Prisma schema. For example:
+  * Replace this default advisory JSDoc with your own documentation about enum Foo
+  * by documenting it in your Prisma schema. For example:
   *
   *
   * \`\`\`prisma
@@ -98,7 +100,9 @@ declare namespace $Types {
   * }
   * \`\`\`
   * 
-  * Learn more about Prisma Schema documentation comments [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+  * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+  *
+  * Contains these members: a
   *
   * @example
   *
@@ -174,10 +178,12 @@ declare namespace $Types {
   // Enums
 
   /**
-    * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+    * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
     *
     * Some documentation
     *
+    * Contains these members: a
+    *
     * @example
     *
     * import { enumType } from 'nexus'
@@ -223,10 +229,12 @@ declare namespace $Types {
 //
 
 /**
-  * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+  * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
   *
   * Some documentation
   *
+  * Contains these members: a
+  *
   * @example
   *
   * import { enumType } from 'nexus'

tests/unit/typescriptDeclarationFile/__snapshots__/enumDoc.test.ts.snap

@@ -21,10 +21,12 @@ declare namespace $Types {
   // Enums
 
   /**
-    * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+    * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
     *
     * Some documentation
     *
+    * Contains these members: a
+    *
     * @example
     *
     * import { enumType } from 'nexus'
@@ -70,10 +72,12 @@ declare namespace $Types {
 //
 
 /**
-  * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+  * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
   *
   * Some documentation
   *
+  * Contains these members: a
+  *
   * @example
   *
   * import { enumType } from 'nexus'
@@ -148,12 +152,12 @@ declare namespace $Types {
   // Enums
 
   /**
-    * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+    * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
     *
-    * ### ️⚠️ Missing Documentation for this Enum
+    * ### ️⚠️ You have not writen documentation for enum Foo
     * 
-    * Automatically ✨ enrich this JSDoc with information about your enum
-    * type by documenting it in your Prisma schema. For example:
+    * Replace this default advisory JSDoc with your own documentation about enum Foo
+    * by documenting it in your Prisma schema. For example:
     *
     *
     * \`\`\`prisma
@@ -163,7 +167,9 @@ declare namespace $Types {
     * }
     * \`\`\`
     * 
-    * Learn more about Prisma Schema documentation comments [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+    * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+    *
+    * Contains these members: a
     *
     * @example
     *
@@ -210,12 +216,12 @@ declare namespace $Types {
 //
 
 /**
-  * Nexus \`enumType\` configuration based on the \`Foo\` enum in your Prisma schema.
+  * Generated Nexus \`enumType\` configuration based on your Prisma schema's enum \`Foo\`.
   *
-  * ### ️⚠️ Missing Documentation for this Enum
+  * ### ️⚠️ You have not writen documentation for enum Foo
   * 
-  * Automatically ✨ enrich this JSDoc with information about your enum
-  * type by documenting it in your Prisma schema. For example:
+  * Replace this default advisory JSDoc with your own documentation about enum Foo
+  * by documenting it in your Prisma schema. For example:
   *
   *
   * \`\`\`prisma
@@ -225,7 +231,9 @@ declare namespace $Types {
   * }
   * \`\`\`
   * 
-  * Learn more about Prisma Schema documentation comments [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+  * Learn more about documentation comments in Prisma schema files [here](https://www.prisma.io/docs/concepts/components/prisma-schema#comments).
+  *
+  * Contains these members: a
   *
   * @example
   *