docs: cover root types with jsdoc

src/definitions/definitionBlocks.ts

@@ -6,8 +6,10 @@ import { AllNexusInputTypeDefs, AllNexusOutputTypeDefs, NexusWrapKind } from './
 import { BaseScalars } from './_types'
 
 export interface CommonFieldConfig {
+  //todo
   /** The description to annotate the GraphQL SDL */
   description?: string
+  //todo
   /**
    * Info about a field deprecation. Formatted as a string and provided with the deprecated directive on
    * field/enum types and as a comment on input fields.
@@ -372,7 +374,7 @@ export class OutputDefinitionBlock<TypeName extends string> {
   }
 
   /**
-   * [API Docs](https://nxs.li/docs/api/nonNull) | [Nexus Nullability
+   * [API Docs](https://nxs.li/docs/api/nonNull) | [Nullability
    * Guide](https://nexusjs.org/docs/guides/nullability) | [GraphQL 2018
    * Spec](https://spec.graphql.org/June2018/#sec-Type-System.Non-Null)
    *
@@ -410,7 +412,7 @@ export class OutputDefinitionBlock<TypeName extends string> {
   }
 
   /**
-   * [API Docs](https://nxs.li/docs/api/null) | [Nexus Nullability
+   * [API Docs](https://nxs.li/docs/api/null) | [Nullability
    * Guide](https://nexusjs.org/docs/guides/nullability) | [GraphQL 2018
    * Spec](https://spec.graphql.org/June2018/#sec-Type-System.Non-Null)
    *

src/definitions/mutationField.ts

@@ -5,12 +5,122 @@ export type MutationFieldConfig<FieldName extends string> =
   | FieldOutConfig<'Mutation', FieldName>
   | (() => FieldOutConfig<'Mutation', FieldName>)
 
+/**
+ * [API Docs](https://nexusjs.org/docs/api/mutation-field) | [2018 GraphQL
+ * Spec](https://spec.graphql.org/June2018/#sec-Mutation)
+ *
+ * Define one or more fields on the Mutation type.
+ *
+ * Use this if you are going to modularize your schema and thus be wanting to contribute fields to Mutation
+ * type from multiple modules. You do not have to have previously defined a Mutatin type before using this.
+ * If you haven't Nexus will create one automatically for you.
+ *
+ * This is shorthand for:
+ *
+ * `extendType({ type: 'Mutation' })`
+ *
+ * If you need to leverage plugins or define multiple fields then use the typeBuilder overload variant of this
+ * function. Otherwise you may prefer to the field name/config variant.
+ *
+ * @example
+ *   // User.ts
+ *   // Overload 1: Type Builder
+ *
+ *   mutationField((t) => {
+ *     t.field('signup', {
+ *       type: 'User',
+ *       args: {
+ *         email: stringArg(),
+ *       },
+ *       // ...
+ *     })
+ *     t.field('deactivate', {
+ *       type: 'User',
+ *       args: {
+ *         userId: idArg(),
+ *       },
+ *       // ...
+ *     })
+ *   })
+ *
+ * @example
+ *   // User.ts
+ *   // Overload 2: Field Name/Config
+ *
+ *   mutationField('signup', {
+ *     type: 'User',
+ *     args: {
+ *       email: stringArg(),
+ *     },
+ *     // ...
+ *   })
+ *
+ * @param typeBuilder The same as the "definition" method you define on object type configurations.
+ */
 export function mutationField(
-  fieldFn: (t: OutputDefinitionBlock<'Mutation'>) => void
+  typeBuilder: (t: OutputDefinitionBlock<'Mutation'>) => void
 ): NexusExtendTypeDef<'Mutation'>
 
+/**
+ * [API Docs](https://nexusjs.org/docs/api/mutation-field) | [2018 GraphQL
+ * Spec](https://spec.graphql.org/June2018/#sec-Mutation)
+ *
+ * Define one or more fields on the mutation type.
+ *
+ * The Mutation type is one of three [root types](https://spec.graphql.org/June2018/#sec-Root-Operation-Types)
+ * in GraphQL and its fields represent API operations your clients can run that may have side-effects.
+ *
+ * Use this instead of mutationType if you are going to modularize your schema and thus be wanting to
+ * contribute fields to Mutation type from multiple modules. You do not have to have previously defined a
+ * Mutatin type before using this. If you haven't Nexus will create one automatically for you.
+ *
+ * This is shorthand for:
+ *
+ * `extendType({ type: 'Mutation' })`
+ *
+ * If you need to leverage plugins or define multiple fields then use the typeBuilder overload variant of this
+ * function. Otherwise you may prefer to the field name/config variant.
+ *
+ * @example
+ *   // User.ts
+ *   // Overload 1: Type Builder
+ *
+ *   mutationField((t) => {
+ *     t.field('signup', {
+ *       type: 'User',
+ *       args: {
+ *         email: stringArg(),
+ *       },
+ *       // ...
+ *     })
+ *     t.field('deactivate', {
+ *       type: 'User',
+ *       args: {
+ *         userId: idArg(),
+ *       },
+ *       // ...
+ *     })
+ *   })
+ *
+ * @example
+ *   // User.ts
+ *   // Overload 2: Field Name/Config
+ *
+ *   mutationField('signup', {
+ *     type: 'User',
+ *     args: {
+ *       email: stringArg(),
+ *     },
+ *     // ...
+ *   })
+ *
+ * @param name The name of the field on the Mutation type. Names are case‐sensitive and must conform to pattern:
+ *
+ *     [_A-Za-z][_0-9A-Za-z]*
+ * @param config The same type of configuration you would pass to t.field("...", config)
+ */
 export function mutationField<FieldName extends string>(
-  fieldName: FieldName,
+  name: FieldName,
   config: MutationFieldConfig<FieldName>
 ): NexusExtendTypeDef<'Mutation'>
 

src/definitions/mutationType.ts

@@ -1,5 +1,44 @@
 import { NexusObjectTypeConfig, objectType } from './objectType'
 
+/**
+ * [2018 GraphQL Spec](https://spec.graphql.org/June2018/#sec-Mutation)
+ *
+ * Define a Mutation type.
+ *
+ * The Mutation type is one of three [root types](https://spec.graphql.org/June2018/#sec-Root-Operation-Types)
+ * in GraphQL and its fields represent API operations your clients can run that may have side-effects.
+ *
+ * You can only have one of these in your schema. If you are going to modularize your schema and thus be
+ * wanting to contribute fields to Mutation type from multiple modules then use
+ * [mutationField](https://nxs.li/docs/api/mutation-field) intead.
+ *
+ * This is a shorthand for:
+ *
+ * `objectType({ name: 'Mutation' })`
+ *
+ * @example
+ *   mutationType({
+ *     definitin(t) {
+ *       t.field('signup', {
+ *         type: 'User',
+ *         args: {
+ *           email: stringArg(),
+ *         },
+ *         // ...
+ *       })
+ *       t.field('buy', {
+ *         type: 'Recipet',
+ *         args: {
+ *           productId: idArg(),
+ *         },
+ *         // ...
+ *       })
+ *     },
+ *   })
+ *
+ * @param config Specify your Mutation type's fields, description, and more. See each config property's jsDoc
+ *     for more detail.
+ */
 export function mutationType(config: Omit<NexusObjectTypeConfig<'Mutation'>, 'name'>) {
   return objectType({ ...config, name: 'Mutation' })
 }

src/definitions/nonNull.ts

@@ -1,6 +1,6 @@
+import { isNonNullType, isType } from 'graphql'
 import { isNexusNonNullTypeDef, isNexusNullTypeDef, isNexusStruct, NexusNonNullableTypes } from './wrapping'
 import { NexusTypes, withNexusSymbol } from './_types'
-import { isNonNullType, isType } from 'graphql'
 
 export class NexusNonNullDef<TypeName extends NexusNonNullableTypes> {
   // @ts-ignore
@@ -16,6 +16,59 @@ export class NexusNonNullDef<TypeName extends NexusNonNullableTypes> {
 
 withNexusSymbol(NexusNonNullDef, NexusTypes.NonNull)
 
+/**
+ * [API Docs](https://nxs.li/docs/api/nonNull) | [Nullability Guide](https://nxs.li/guides/nullability) |
+ * [2018 GraphQL Spec](https://spec.graphql.org/June2018/#sec-Type-System.Non-Null)
+ *
+ * Modify a type to be Non-Null.
+ *
+ * In Nexus input postition types are non-null by default so this has no use for them (until you've changed
+ * the default). On the other hand output postition types are nullable by default so use this to modify them
+ * (until you've changed the default).
+ *
+ * If you find yourself using this a large majority of the time then consider changing your nullability defaults.
+ *
+ * @example
+ *   objectType({
+ *     name: 'User',
+ *     nonNullDefaults: {
+ *       inputs: false,
+ *     },
+ *     definition(t) {
+ *       t.field('id', {
+ *         type: nonNull('ID'),
+ *       })
+ *       t.field('bio', {
+ *         args: {
+ *           format: nonNull(booleanArg()),
+ *           maxWords: intArg(),
+ *         },
+ *         type: 'String',
+ *       })
+ *     },
+ *   })
+ *
+ *   // GraphQL SDL
+ *   // -----------
+ *   //
+ *   // type User {
+ *   //   id: ID!
+ *   //   bio(maxWords: Int, format: Boolean!): String
+ *   // }
+ *
+ * @param type The type to wrap in Non-Null. This may be expressed in one of three ways:
+ *
+ * 1. As string literals matching the name of a builtin scalar. E.g.: 'ID', 'String', ...
+ *
+ * 2. As string literals matching the name of another type. E.g.: 'User', 'Location', ... Thanks to
+ *     [Nexus' reflection
+ *     system](https://nxs.li/guides/reflection) this is typesafe and autocompletable. This is the idiomatic
+ *     approach in Nexus because it avoids excessive importing and circular references.
+ *
+ * 3. As references to other enums or object type definitions. E.g.: User, Location
+ *
+ * You may also use other type modifier helpers like list() which in turn accept one of the three
+ */
 export function nonNull<TypeName extends NexusNonNullableTypes>(type: TypeName) {
   if (isNexusNonNullTypeDef(type) || isNonNullType(type)) {
     return type

src/definitions/nullable.ts

@@ -16,7 +16,59 @@ export class NexusNullDef<TypeName extends NexusNullableTypes> {
 
 withNexusSymbol(NexusNullDef, NexusTypes.Null)
 
-/** Null() */
+/**
+ * [API Docs](https://nxs.li/docs/api/nonNull) | [Nullability Guide](https://nxs.li/guides/nullability) |
+ * [2018 GraphQL Spec](https://spec.graphql.org/June2018/#sec-Type-System.Non-Null)
+ *
+ * Remove the Non-Null wrapper from a type, if present.
+ *
+ * In Nexus input postition types are non-null by default so this is useful to modify them (until you've
+ * changed the default). On the other hand output postition types are nullable by default so this has no use
+ * for them (until you've changed the default).
+ *
+ * If you find yourself using this a large majority of the time then consider changing your nullability defaults.
+ *
+ * @example
+ *   objectType({
+ *     name: 'User',
+ *     nonNullDefaults: {
+ *       outputs: true,
+ *     },
+ *     definition(t) {
+ *       t.field('id', {
+ *         type: 'ID',
+ *       })
+ *       t.field('bio', {
+ *         args: {
+ *           format: booleanArg(),
+ *           maxWords: nullable(intArg()),
+ *         },
+ *         type: nullable('String'),
+ *       })
+ *     },
+ *   })
+ *
+ *   // GraphQL SDL
+ *   // -----------
+ *   //
+ *   // type User {
+ *   //   id: ID!
+ *   //   bio(maxWords: Int, format: Boolean!): String
+ *   // }
+ *
+ * @param type The type to wrap in Non-Null. This may be expressed in one of three ways:
+ *
+ * 1. As string literals matching the name of a builtin scalar. E.g.: 'ID', 'String', ...
+ *
+ * 2. As string literals matching the name of another type. E.g.: 'User', 'Location', ... Thanks to
+ *     [Nexus' reflection
+ *     system](https://nxs.li/guides/reflection) this is typesafe and autocompletable. This is the idiomatic
+ *     approach in Nexus because it avoids excessive importing and circular references.
+ *
+ * 3. As references to other enums or object type definitions. E.g.: User, Location
+ *
+ * You may also use other type modifier helpers like list() which in turn accept one of the three
+ */
 export function nullable<TypeName extends NexusNullableTypes>(type: TypeName) {
   if (isNexusNonNullTypeDef(type)) {
     return new NexusNullDef(type.ofNexusType)