How to explain in GraphQL-esque

Explaining in GraphQL is easy. Write single line comments with #. Offer more verbosity in multi-line descriptions with bracketing """.

Single Line Comment

Start exactly with # to comment a simple single line.

# A snack may or may not be delicious.
type Snack {
  name: String!,
  delicious: Boolean!
}

Perfectly safe in a GraphQL schema.

Multi-Line Description

Bracket a multi-line comment with """. GraphQL schema tools are smart. Multi-line descriptions are useful to tools like Graphiql.

"""
A shirt.
It is a really simple type.
"""
type Shirt {
"""
The size of the shirt, like small or medium.
The value depends on the language of the user.
"""
  size: String!,
  threads: Int!,
  thickness: Float!
}

Also safe in a GraphQL schema.

Query Comment

A single line comment is safe in a query. A multi-line description is not.

{
  snack {
    # this comment is safe
    name
  }
}

Possible in a GraphQL query.

Lack of comments is like a pandemic

GraphQL is for people. I don't disagree with code clarity as documentation. Sometimes people who have nothing to do with code may read a GraphQL text block. It's shocking. Let's not forget that comments are fundamentally for our hyper connected readers. I don't know if there is a better way.