Descriptions

GraphQL supports adding descriptions to types, fields, 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 implementation 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

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

Playground

"""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

A @ symbol in a description's text, for example in a GitHub handle, starts a docblock tag, so the description is truncated there. To avoid this, you can wrap the handle in quotes or backticks.

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