Descriptions

GraphQL supports adding descriptions to types, fields, and arguments and more. These descriptions are used by tools like Graphiql and editor integrations to provide context to developers.

Grats makes it easy to populate these descriptions and keep them in sync with the implementaiton by using the leading free text in your docblocks as that construct's description.

tip

Both TypeScript and GraphQL expect descriptions to be written in Markdown.

See Comment Syntax for more details.

Example

TypeScript

/**
 * A registered user of the system.
 * @gqlType
 */
class User {
  /**
   * A friendly greeting for the user, intended for
   * their first visit.
   * @gqlField
   */
  hello(args: {
    /** The salutation to use */
    greeting: string;
  }): string {
    return `${args.greeting} World`;
  }
}

Playground

GraphQL

"""A registered user of the system."""
type User {
  """
  A friendly greeting for the user, intended for
  their first visit.
  """
  hello(
    """The salutation to use"""
    greeting: String!
  ): String
}

tip

Depending upon your version of TypeScript, descriptions with a @ symbol in their text, for example a GitHub handle, may get truncated. To avoid this, you can wrap the tag in quotes or backticks.

/** This comment was added by `@captbaritone`. */

Limitations

caution

In some cases, TypeScript does not support "attaching" docblock comments to certain constructs. In these cases, Grats is currently unable to extract descriptions.

For example, Grats is not currently able to attach descriptions to enum values defined using a type union.

/** @gqlEnum */
type GreetingStyle =
  /** For a business greeting */
  | "formal"
  /** For a friendly greeting */
  | "casual";

Playground

Will incorrectly extract this GraphQL:

enum GreetingStyle {
  casual
  formal
}