docs: cover isTypeOf method with jsdoc

src/definitions/definitionBlocks.ts

@@ -16,12 +16,35 @@ export interface CommonFieldConfig {
 }
 
 export type CommonOutputFieldConfig<TypeName extends string, FieldName extends string> = CommonFieldConfig & {
-  /** Arguments for the field */
+  /** Arguments for this field. */
   args?: ArgsRecord
   /**
-   * Custom extensions, as supported in graphql-js
+   * Data that will be added to the field-level [extensions field on the graphql-js type def
+   * instances](https://github.com/graphql/graphql-js/issues/1527) resulting from makeSchema. Useful for some
+   * graphql-js based tools like [join-monster](https://github.com/join-monster/join-monster) which rely on
+   * looking for special data here.
    *
-   * @see https://github.com/graphql/graphql-js/issues/1527
+   * @example
+   *   // taken from: https://github.com/graphql-nexus/schema/issues/683#issuecomment-735711640
+   *
+   *   const User = objectType({
+   *     name: 'User',
+   *     extensions: {
+   *       joinMonster: {
+   *         sqlTable: 'USERS',
+   *         uniqueKey: 'USER_ID',
+   *       },
+   *     },
+   *     definition(t) {
+   *       t.id('id', {
+   *         extensions: {
+   *           joinMonster: {
+   *             sqlColumn: 'USER_ID',
+   *           },
+   *         },
+   *       })
+   *     },
+   *   })
    */
   extensions?: GraphQLFieldConfig<any, any>['extensions']
 } & NexusGenPluginFieldConfig<TypeName, FieldName>
@@ -30,9 +53,9 @@ export type CommonInputFieldConfig<TypeName extends string, FieldName extends st
   /** The default value for the field, if any */
   default?: GetGen3<'inputTypes', TypeName, FieldName>
   /**
-   * Custom extensions, as supported in graphql-js
-   *
-   * @see https://github.com/graphql/graphql-js/issues/1527
+   * Data that will be added to the field-level [extensions field on the graphql-js type def
+   * instances](https://github.com/graphql/graphql-js/issues/1527) resulting from makeSchema. Useful for some
+   * graphql-js based tools which rely on looking for special data here.
    */
   extensions?: GraphQLInputFieldConfig['extensions']
 } & NexusGenPluginFieldConfig<TypeName, FieldName>
@@ -65,6 +88,18 @@ export interface OutputScalarConfig<TypeName extends string, FieldName extends s
    * ...then the default resolver will be available, whose behaviour is to simply return that field from the
    * received source type.
    *
+   * @example
+   *   export const Query = queryType({
+   *     definition(t) {
+   *       t.list.field('posts', {
+   *         type: 'Post',
+   *         resolve(_, __, ctx) {
+   *           return ctx.db.post.findMany({ where: { published: true } })
+   *         },
+   *       })
+   *     },
+   *   })
+   *
    * @param source The [source data](https://nxs.li/guides/source-types) for the GraphQL object that this
    *     field belongs to, unless this is a root
    *     field (any field on a [root

src/definitions/objectType.ts

@@ -129,10 +129,34 @@ export type NexusObjectTypeConfig<TypeName extends string> = {
    *   }
    */
   rootTyping?: RootTypingDef
+
   /**
-   * Custom extensions, as supported in graphql-js
+   * Data that will be added to the field-level [extensions field on the graphql-js type def
+   * instances](https://github.com/graphql/graphql-js/issues/1527) resulting from makeSchema. Useful for some
+   * graphql-js based tools like [join-monster](https://github.com/join-monster/join-monster) which rely on
+   * looking for special data here.
+   *
+   * @example
+   *   // taken from: https://github.com/graphql-nexus/schema/issues/683#issuecomment-735711640
    *
-   * @see https://github.com/graphql/graphql-js/issues/1527
+   *   const User = objectType({
+   *     name: 'User',
+   *     extensions: {
+   *       joinMonster: {
+   *         sqlTable: 'USERS',
+   *         uniqueKey: 'USER_ID',
+   *       },
+   *     },
+   *     definition(t) {
+   *       t.id('id', {
+   *         extensions: {
+   *           joinMonster: {
+   *             sqlColumn: 'USER_ID',
+   *           },
+   *         },
+   *       })
+   *     },
+   *   })
    */
   extensions?: GraphQLObjectType['extensions']
   /**

src/typegenAbstractTypes.ts

@@ -68,15 +68,53 @@ export type IsTypeOfHandler<TypeName extends string> = (
  */
 // prettier-ignore
 export type MaybeTypeDefConfigFieldIsTypeOf<TypeName extends string> =
-IsFeatureEnabled2<'abstractTypeStrategies', 'isTypeOf'> extends false // is isTypeOf strategy disabled ?
-? {} // then hide isTypeOf property entirely
-: IsStrategyResolveTypeImplementedInAllAbstractTypes<TypeName> extends true // is resolveType implemented in all abstract types where TypeName is a member?
-  ? { isTypeOf?: IsTypeOfHandler<TypeName> } // then make isTypeOf optional
-  : IsFeatureEnabled2<'abstractTypeStrategies', '__typename'> extends true // is __typename strategy is enabled?
-    ? { isTypeOf?: IsTypeOfHandler<TypeName> } // then make isTypeOf optional
-    : AbstractTypeNames<TypeName> extends never  // is TypeName not part of any abstract type?
-    ? { isTypeOf?: IsTypeOfHandler<TypeName> } // then make isTypeOf optional
-    : { isTypeOf: IsTypeOfHandler<TypeName> } // otherwise, make it required
+  // is isTypeOf strategy disabled ?
+  IsFeatureEnabled2<'abstractTypeStrategies', 'isTypeOf'> extends false
+  // then hide isTypeOf property entirely
+  ? {}
+  // is TypeName not part of any abstract type?
+  : AbstractTypeNames<TypeName> extends never
+  // then make isTypeOf optional
+  ? {
+      /** C */
+      isTypeOf?: IsTypeOfHandler<TypeName>
+    }
+  // is resolveType implemented in all abstract types where TypeName is a member?
+  : IsStrategyResolveTypeImplementedInAllAbstractTypes<TypeName> extends true
+  // then make isTypeOf optional
+  ? {
+      /**
+       * [Abstract Types guide](https://nxs.li/guides/abstract-types)
+       *
+       * Implement the [modular strategy](https://nxs.li/guides/abstract-types/modular-strategy).
+       *
+       * Either you have implemented the [centralized strategy
+       * (resolveType)](https://nxs.li/guides/abstract-types/centralized-strategy) in all abstract
+       * types that this type shows up in or this type does not show up in any abstract types. Either
+       * way, and therefore, implementing this ***will do nothing***.
+       * 
+       */
+      isTypeOf?: IsTypeOfHandler<TypeName>
+    }
+  // is __typename strategy is enabled?
+  : IsFeatureEnabled2<'abstractTypeStrategies', '__typename'> extends true
+  // then make isTypeOf optional
+  ? {
+      /** B */
+      isTypeOf?: IsTypeOfHandler<TypeName>
+    }
+  // otherwise, make it required
+  : {
+      /**
+       * [Abstract Types guide](https://nxs.li/guides/abstract-types)
+       *
+       * Implement the [modular strategy](https://nxs.li/guides/abstract-types/modular-strategy).
+       *
+       * You must implement this because your type shows up in one or more abstract types that do
+       * not implement the [centralized strategy](https://nxs.li/guides/abstract-types/centralized-strategy).
+       */
+      isTypeOf: IsTypeOfHandler<TypeName>
+    }
 
 /**
  * Get an object with the `resolveType` field if applicable for the given abstract Type.