docs: cover objectType with jsdocs (#703)

graphql-nexus · Dec 4, 2020 · 2c8102b · 2c8102b
1 parent c16f6c6
commit 2c8102b
Show file tree

Hide file tree

Showing 20 changed files with 270 additions and 163 deletions.
diff --git a/docs/content/014-guides/020-schema.mdx b/docs/content/014-guides/020-schema.mdx
@@ -24,10 +24,7 @@ We will now begin exploring the GraphQL schema building parts of the schema comp
 <!-- prettier-ignore -->
 ```ts
                                       objectType({
-// The singleton instance of ---------^      |
-// the Nexus schema component                |
-//                                           |
-// A type Builder method --------------------^
+// A type Builder method -------------^
                                         name: 'Foo',
 // The name of this type ----------------------^
                                         definition(t) {

diff --git a/package.json b/package.json
@@ -91,6 +91,7 @@
     "jest-watch-typeahead": "^0.6.1",
     "lint-staged": "^7.3.0",
     "prettier": "^2.0.5",
+    "prettier-plugin-jsdoc": "^0.2.5",
     "sort-package-json": "^1.22.1",
     "ts-jest": "^26.4.4",
     "ts-morph": "^8.2.0",

diff --git a/src/core.ts b/src/core.ts
@@ -9,18 +9,20 @@ export * from './definitions/extendInputType'
 export * from './definitions/extendType'
 export * from './definitions/inputObjectType'
 export * from './definitions/interfaceType'
+export * from './definitions/list'
 export * from './definitions/mutationField'
+export * from './definitions/mutationType'
+export * from './definitions/nonNull'
+export * from './definitions/nullable'
 export * from './definitions/objectType'
 export * from './definitions/queryField'
+export * from './definitions/queryType'
 export * from './definitions/scalarType'
 export * from './definitions/subscriptionField'
 export * from './definitions/subscriptionType'
 export * from './definitions/unionType'
 export * from './definitions/wrapping'
 export * from './definitions/_types'
-export * from './definitions/list'
-export * from './definitions/nonNull'
-export * from './definitions/nullable'
 export * from './dynamicMethod'
 export * from './plugin'
 export * from './plugins'

diff --git a/src/definitions/_types.ts b/src/definitions/_types.ts
@@ -55,41 +55,28 @@ export enum NexusTypes {
 }
 
 export interface DeprecationInfo {
-  /**
-   * Reason for the deprecation.
-   */
+  /** Reason for the deprecation. */
   reason: string
-  /**
-   * Date | YYYY-MM-DD formatted date of when this field
-   * became deprecated.
-   */
+  /** Date | YYYY-MM-DD formatted date of when this field became deprecated. */
   startDate?: string | Date
-  /**
-   * Field or usage that replaces the deprecated field.
-   */
+  /** Field or usage that replaces the deprecated field. */
   supersededBy?: string
 }
 
+/**
+ * [Nexus Nullability Guide](https://nxs.li/guides/nullability)
+ *
+ * Configures the default nullability for fields and arguments.
+ */
 export interface NonNullConfig {
   /**
-   * Whether output fields are non-null by default.
-   *
-   * type Example {
-   *   field: String!
-   *   otherField: [String!]!
-   * }
+   * Whether output field (object type fields) types are non-null by default.
    *
    * @default false
    */
   output?: boolean
   /**
-   * Whether input fields (field arguments, input type members)
-   * are non-null by default.
-   *
-   * input Example {
-   *   field: String
-   *   something: [String]
-   * }
+   * Whether input field (field arguments, input object type fields) types are non-null by default.
    *
    * @default false
    */
@@ -117,16 +104,16 @@ export type RootTypingDef = string | TypingImport
 export type RootTypings = Record<string, string | TypingImport>
 
 export interface TypingImport {
-  /**
-   * Node module, or absolute path to import the type from.
-   */
+  /** The name of a package installed in your project or absolute path to a module in your project. */
   path: string
-  /**
-   * Name of the type we want to reference in the `path`
-   */
+  /** The name of a type being exported from the package/module (specified in path) that you want to use. */
   name: string
   /**
-   * Name we want the imported type to be referenced as
+   * The name you want the imported type to be referenced as in the typegen.
+   *
+   * This is useful when there is already a typegen import whose name would conflict with this type name.
+   *
+   * Default :: By default no import alias will be used.
    */
   alias?: string
 }
@@ -173,63 +160,62 @@ export type NexusGraphQLSchema = Omit<GraphQLSchema, 'extensions'> & {
 
 export type NexusFeaturesInput = {
   /**
-   * Toggle runtime checks for correct implementation of abstract types. This is
-   * a redundant check Nexus makes over the existing static typings it provides.
-   *
-   * @remarks
+   * Toggle runtime checks for correct implementation of abstract types. This is a redundant check Nexus makes
+   * over the existing static typings it provides.
    *
-   * This is useful for beginners because Nexus can give clear concise error
-   * messages unlike the static type errors.
+   * Remarks :: This is useful for beginners because Nexus can give clear concise error messages unlike the
+   * static type errors.
    *
-   * Note that if you enable the "abstractTypeStrategies.__typename" feature
-   * then this feature will be automatically disabled. For why this is, see that
-   * features' remarks.
+   * Note that if you enable the "abstractTypeStrategies.__typename" feature then this feature will be
+   * automatically disabled. For why this is, see that features' remarks.
    */
   abstractTypeRuntimeChecks?: boolean
   /**
-   * Toggle abstract-type strategies. For more detail about this feature please refer to to the [abstract types guide](https://nxs.li/guides/abstract-types).
+   * Toggle abstract-type strategies. For more detail about this feature please refer to to the [abstract
+   * types guide](https://nxs.li/guides/abstract-types).
    *
-   * If you plan on enabling multiple strategies and you've never done so then please [read the guide about using multiple strategies](https://nxs.li/guides/abstract-types/using-multiple-strategies) as there are a few quirks to be aware of.
+   * If you plan on enabling multiple strategies and you've never done so then please [read the guide about
+   * using multiple strategies](https://nxs.li/guides/abstract-types/using-multiple-strategies) as there are
+   * a few quirks to be aware of.
    *
    * @default
-   *
-   * {
+   *  {
    *    resolveType: true,
    *    __typename: false
    *    isTypeOf: false,
    * }
    */
   abstractTypeStrategies?: {
     /**
-     * The Modular abstract type strategy. Every member object of an abstract
-     * type (union members or interface implementors) will generally be required
-     * to implement isTypeOf method. Nexus will not require it in cases where it
-     * detects you have implemented another strategy. For more detail see the
-     * guide for the [Modular Abstract Type Strategy](https://nxs.li/guides/abstract-types/modular-strategy).
+     * The Modular abstract type strategy. Every member object of an abstract type (union members or interface
+     * implementors) will generally be required to implement isTypeOf method. Nexus will not require it in
+     * cases where it detects you have implemented another strategy. For more detail see the guide for the
+     * [Modular Abstract Type Strategy](https://nxs.li/guides/abstract-types/modular-strategy).
      */
     isTypeOf?: boolean
     /**
-     * The Centralized abstract type strategy. Every abstract type (union or
-     * interface) will generally be required to implement its resolveType
-     * method. Nexus will not require it in cases where it detects you have
-     * implemented another strategy. For more detail see the guide for the [Central Abstract Type Strategy](https://nxs.li/guides/abstract-types/centralized-strategy).
+     * The Centralized abstract type strategy. Every abstract type (union or interface) will generally be
+     * required to implement its resolveType method. Nexus will not require it in cases where it detects you
+     * have implemented another strategy. For more detail see the guide for the [Central Abstract Type
+     * Strategy](https://nxs.li/guides/abstract-types/centralized-strategy).
      */
     resolveType?: boolean
     /**
-     * The Discriminant Model Field strategy. In this mode the resolvers of fields typed as
-     * abstract types will be required to include "__typename" field in the
-     * returned data. For more detail see the guide for the [Discriminant Model Field Strategy](https://nxs.li/guides/abstract-types/discriminant-model-field-strategy).
-     *
-     * @warning
-     *
-     * When this strategy is enabled in conjunction with other strategies the "abstractTypeRuntimeChecks" feature will
-     * automatically be disabled. This is because it is not practical at runtime
-     * to find out if resolvers will return objects that include the
-     * "__typename" field. This trade-off can be acceptable since the runtime checks are a redundant safety
-     * measure over the static typing. So as long as you are not ignoring static errors related to Nexus' abstract type type checks then you then you should still have a safe implementation.
+     * The Discriminant Model Field strategy. In this mode the resolvers of fields typed as abstract types
+     * will be required to include "__typename" field in the returned data. For more detail see the guide for
+     * the [Discriminant Model Field Strategy](https://nxs.li/guides/abstract-types/discriminant-model-field-strategy).
      *
-     * Furthermore another effect is that statically the other strategies will not appear to be _required_, but instead _optional_, while only this one will appear required. However, upon implementing any of the other strategies, this one will not longer be required. This quirk is explained in the guide section about [using multiple strategies](https://nxs.li/guides/abstract-types/using-multiple-strategies).
+     * Warning :: When this strategy is enabled in conjunction with other strategies the
+     * "abstractTypeRuntimeChecks" feature will automatically be disabled. This is because it is not
+     * practical at runtime to find out if resolvers will return objects that include the "__typename" field.
+     * This trade-off can be acceptable since the runtime checks are a redundant safety measure over the
+     * static typing. So as long as you are not ignoring static errors related to Nexus' abstract type type
+     * checks then you then you should still have a safe implementation.
      *
+     * Furthermore another effect is that statically the other strategies will not appear to be _required_,
+     * but instead _optional_, while only this one will appear required. However, upon implementing any of
+     * the other strategies, this one will not longer be required. This quirk is explained in the guide
+     * section about [using multiple strategies](https://nxs.li/guides/abstract-types/using-multiple-strategies).
      */
     __typename?: boolean
   }

diff --git a/src/definitions/mutationType.ts b/src/definitions/mutationType.ts
@@ -0,0 +1,5 @@
+import { NexusObjectTypeConfig, objectType } from './objectType'
+
+export function mutationType(config: Omit<NexusObjectTypeConfig<'Mutation'>, 'name'>) {
+  return objectType({ ...config, name: 'Mutation' })
+}